diff options
| -rw-r--r-- | spm-slides.tex | 46 |
1 files changed, 30 insertions, 16 deletions
diff --git a/spm-slides.tex b/spm-slides.tex index 7516116..4938ee7 100644 --- a/spm-slides.tex +++ b/spm-slides.tex @@ -698,22 +698,36 @@ index 84e3f68..fd54c16 100644 {\bf Communication channels}. Your presence on the list/forum does not imply a commitment to answer all questions or implement all feature requests. -{\bf Developer guidelines}. Basic elements: * pointers to forums * instructions on how to report bugs and submit patches * some indication of how development is usually done and how decisions are made — is the project a -benevolent dictatorship, a democracy, or something else. Example: \url{https://wiki.documentfoundation.org/Development}. - -{\bf Documentation.} Maintain FAQs (both online and in the -distribution). There needs to be something for people to read, even if -it's rudimentary and incomplete. The most important documentation for -initial users is the basics: how to quickly set up the software, an -overview of how it works, perhaps some guides to doing common tasks -(tutorial). Plain text, HTML, Markdown, reStructuredText, Read The -Docs (an online documentation tool at \url{https://readthedocs.org}). Tell the readers the known -deficiencies, issues. {\bf Put everything in one page}. - -{\bf Developer documentation}. Developer guidelines tell programmers how to get along with each -other; developer documentation tells them how to get along with the code itself. - -{\bf Hosting}. A website for users and a website for developers. +{\bf Developer guidelines}. For potential contributors. Basic elements: * +pointers to forums * instructions on how to report bugs and submit patches +* some indication of how development is usually done and how decisions are +made — is the project a benevolent dictatorship (veto power), a democracy, +or something else. Good examples: +\begin{itemize} +\item \url{https://wiki.documentfoundation.org/Development}. +\item \url{https://subversion.apache.org/docs/community-guide/} +\item \url{https://www.apache.org/foundation/how-it-works.html} +\item \url{https://www.apache.org/foundation/voting.html} +\end{itemize} +Contrast Developer Guidelines with Developer Documentation. + +{\bf Documentation.} Essential. People need something to read about your project. Make people's +lives easier. Maintain FAQs (both online and in the distribution). An all-in-one page so that +people can search. Fine to be rudimentary and incomplete. The most important documentation for +initial users is the basics: how to quickly set up the software, an overview of how it works, +perhaps some guides to doing common tasks (tutorial). Plain text, HTML, Markdown, {\em +reStructuredText}, Read The Docs (an online documentation tool at \url{https://readthedocs.org}). +Tell the readers the {\bf known deficiencies}, issues. {\bf Put everything in one page}. Hard to +see things form the reader's point of view. + + +{\bf Developer documentation}. Developer guidelines tell programmers how to get along with each +other; developer documentation tells them how to get along with the code itself. Wikis (need to be +actively maintained.) + +{\bf Hosting}. A website for users and a website for developers (code repo, bug tracker, +development wiki, mailing lists, etc). Two sites link to each other. Not important in the beginning. +Canned hosting. {\bf Choosing a license and applying it}. |