From 6c6b23ce669c877a1e07e14eaf50c1f7c5aff17b Mon Sep 17 00:00:00 2001 From: Hui Lan Date: Tue, 9 Apr 2019 09:22:02 +0800 Subject: spm-slides.tex: updated Developer guidelines --- spm-slides.tex | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'spm-slides.tex') diff --git a/spm-slides.tex b/spm-slides.tex index deae10b..573a0e5 100644 --- a/spm-slides.tex +++ b/spm-slides.tex @@ -698,8 +698,13 @@ 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 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. Example: +\url{https://wiki.documentfoundation.org/Development}. Contrast Developer +Guidelines with Developer Documentation. {\bf Documentation.} Maintain FAQs (both online and in the distribution). There needs to be something for people to read, even if -- cgit v1.2.1 From ee761d3ab60193d972e9153a500ce8bb688e6a04 Mon Sep 17 00:00:00 2001 From: Hui Lan Date: Tue, 9 Apr 2019 09:45:41 +0800 Subject: spm-slides.tex: added more examples of developer guidelines --- spm-slides.tex | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'spm-slides.tex') diff --git a/spm-slides.tex b/spm-slides.tex index 573a0e5..6a2f6d1 100644 --- a/spm-slides.tex +++ b/spm-slides.tex @@ -702,9 +702,14 @@ index 84e3f68..fd54c16 100644 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. Example: -\url{https://wiki.documentfoundation.org/Development}. Contrast Developer -Guidelines with Developer Documentation. +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.} Maintain FAQs (both online and in the distribution). There needs to be something for people to read, even if -- cgit v1.2.1 From 9204261047bb7f1b034c77494e65fcd842018c4f Mon Sep 17 00:00:00 2001 From: Hui Lan Date: Tue, 9 Apr 2019 10:12:02 +0800 Subject: spm-slides.tex: updated Documentation and Hosting --- spm-slides.tex | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) (limited to 'spm-slides.tex') diff --git a/spm-slides.tex b/spm-slides.tex index 6a2f6d1..c0e9883 100644 --- a/spm-slides.tex +++ b/spm-slides.tex @@ -711,19 +711,23 @@ or something else. Good examples: \end{itemize} Contrast Developer Guidelines with Developer Documentation. -{\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 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}. -- cgit v1.2.1