diff options
| -rw-r--r-- | spm-slides.tex | 125 |
1 files changed, 89 insertions, 36 deletions
diff --git a/spm-slides.tex b/spm-slides.tex index 518b559..526158f 100644 --- a/spm-slides.tex +++ b/spm-slides.tex @@ -1123,26 +1123,34 @@ You should make efforts to lower this energy threshold. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Starting a New Project} -{\bf Choose a good name}. A bad name can slow down adoption of the project. Project Apollo. Manhattan Project. Gutenberg Project. GNU Project. Gnome Project. +{\bf Choose a good name}. + +A bad name can slow down adoption of the project. + +Good names: Project Apollo, Manhattan Project, Gutenberg Project, GNU Project, Gnome Project. Unique. Easy to remember. -Don't infringe on any trademarks. +Not infringing on any trademarks. + +Spread your project's name. -Spread your project's name. Own your project's name in as many of the relevant namespaces, e.g., twitter, IRC channels, github, weibo, ... The same project name should be available at as many places on the Internet as possible. Why? People can easily find you and know how the project is doing. +Own your project's name in as many of the relevant namespaces, e.g., twitter, IRC channels, github, weibo, ... The same project name should be available at as many places on the Internet as possible. Why? People can easily find you and check how your project is doing. \begin{itemize} \item Internet domain name (a simple URL). For example, https://www.gnome.org \item Twitter handle -\item Username at github. -\item Account name at microblog (weibo.com) -\item IRC (Internet Relay Chat) irc://irc.gnome.org/gnome +\item Username at github +\item Account name at a microblog site (e.g., weibo.com) +\item \href{http://lanlab.org/course/2020s/spm/irc-instruction.txt}{IRC} (Internet Relay Chat). Example: #spm at irc.freenode.org. \end{itemize} -{\bf Have a clear mission statement}. Concrete, limiting and {\em short}. Should target at specific audience. Should be prominently placed on the front page. For example, Hadoop (a distributed computing software which is able sort 1TB data on 910 nodes in less than 4 minutes). +{\bf Have a clear mission statement}. + +Concrete, limiting and {\em short}. Should target at specific audience. Should be prominently placed on the front page. For example, Hadoop (a distributed computing software which is able sort 1TB data on 910 nodes in less than 4 minutes). https://hadoop.apache.org/ @@ -1168,19 +1176,20 @@ The Apache Hadoop software library is a framework that allows for the } Your mission statement is mainly aimed at people with some knowledge -about the related technique. ``Cluster'', ``high-availability''. +about the related technique. Familiar with terms like ``cluster'' and ``high-availability''. + +{\bf State that the project is free}. -{\bf State that the project is free}. The front page must make it -\underline{unambiguously} clear that the project is open source. +The front page must make it \underline{unambiguously} clear that the project is open source. State that project is ``free and open-source'' and give an example license. -Many people forgot to do that. +Many people forget to do that. -In extreme cases, the license was not given anywhere on the web site +In extreme cases, the license was not given anywhere on the project's site at all — the only way to find it was to download the software and look -at a license file inside. +at the license file inside the package. {\tiny @@ -1200,7 +1209,9 @@ See the files GPL2.txt and GPL3.txt for the full license text. \end{verbatim} } -{\bf Demos, screenshots, videos, and example output}. Show that the software works. Prepare a short video (less than 4 minutes) and {\em say} this video is short. +{\bf Demos, screenshots, videos, and example output}. + +Show that the software works. Prepare a short video (less than 4 minutes) and {\em say} this video is short. {\bf Features and requirements list}. @@ -1230,32 +1241,53 @@ REQUIREMENTS \end{verbatim} } -{\bf Development status}. How is the project doing? Promise versus reality. Are the people there, getting things done? {\em How active} is the project developed or maintained? How active is the community. Show News, near-term goals and needs, past releases (with feature lists), timeline of recent releases, bug tracker, discussion forum, and mailing list. Examples: \url{https://launchpad.net/drizzle}, \url{https://launchpad.net/inkscape}, \url{https://launchpad.net/schooltool}. +{\bf Development status}. + +How is the project doing? + +Promise versus reality. + +Are the people there, getting things done? + +{\em How active} is the project developed or maintained? + +How active is the community. + +Show News, near-term goals and needs, past releases (with feature lists), timeline of recent releases, bug tracker, discussion forum, and mailing list. + +Examples: \url{https://launchpad.net/drizzle}, \url{https://launchpad.net/inkscape}, \url{https://launchpad.net/schooltool}. Release notes: \url{http://wiki.inkscape.org/wiki/index.php/Release\_notes} {\bf Development status should always reflect reality}. -Conservativism pays off in the long run; it's always better for the software to be more stable than the user expected than less. Alpha (first release, with known bugs). Beta (serious known bugs fixed, asking users for detailed feedback). Production. + +Conservativism pays off in the long run; it's always better for the software to be more stable than the user expected than less. + +Alpha - first release, with known bugs. + +Beta - serious known bugs fixed, asking users for detailed feedback. + +Production. {\em 10-year Rule}. \href{https://www.joelonsoftware.com/2001/07/21/good-software-takes-ten-years-get-used-to-it/}{Good Software Takes Ten Years. Get Used To it}. Sustained effort is needed. -Lotus Notes. 5 years' work before 1.0, released in 1989. From first line of code in 1984, to 10m users in 1995, 11 years have passed. +Lotus Notes. 5 years' work before 1.0, released in 1989. From first line of code in 1984, to 10m users in 1995, 11 years have passed. + Oracle DB (1977). Microsoft Word 1.0 (1983). All selling billions of dollars yearly. QQ (1998). -Lessons: (i) it takes many years before your software is good enough and serious enough for people to buy it. The Overhype syndrome. (ii) No time to add many wanted features to 1.0 in a short period of time. The Get Big Fast syndrome. (iii) When it is done, it is {\em done}. Additional features are not essential. (iv) ``We’ll Ship It When It’s Ready'' syndrome. +{\underline Lessons:} (i) it takes many years before your software is good enough and serious enough for people to buy it. The Overhype syndrome. (ii) No time to add many wanted features to 1.0 in a short period of time. The Get Big Fast syndrome. (iii) When it is done, it is {\em done}. Additional features are not essential. (iv) ``We’ll Ship It When It’s Ready'' syndrome. Keep 1.0 quiet. We are not writing software any faster than before. We just release more often. +{\bf Downloads}. - - -{\bf Downloads}. Downloadable as source code. Conforming to standard build and installation methods. +Downloadable as source code. Conforming to standard build and installation methods. Otherwise, someone visits a web site, downloads the software, tries to build it, fails, gives up and goes away. {\bf Version control and bug tracker access}. @@ -1272,11 +1304,15 @@ You need a version control repository (e.g., a repo at github, a repo at savanna We also need a bug tracker (visible from the homepage of the -project). For example, Bugzilla. Anyone tried \href{http://www.fogbugz.com/}{FogBugz}? -The {\em higher} the number of bugs -in the database, the {\em better} the project looks. It indicates the -size of user pool and the convenience for reporting bugs. Things to -avoid: (1) no bug database, (2) a nearly empty bug database. +project). + +For example, Bugzilla. Anyone tried \href{http://www.fogbugz.com/}{FogBugz}? + +The {\em higher} the number of bugs in the database, the {\em better} the project looks. + +It \href{https://www.rants.org/2010/01/bugs-users-and-tech-debt/}{indicates} the size of user pool and the convenience for reporting bugs. + +Things to avoid: (1) no bug database, (2) a nearly empty bug database. Example: \url{https://git.launchpad.net/inkscape/diff/src/extension/effect.cpp?id=53578d5ced44808d695e0495d244603a63e6292a} @@ -1329,9 +1365,17 @@ index 84e3f68..fd54c16 100644 } -{\bf Communications channels}. IRC is good. Try \href{http://lanlab.org/course/2020s/spm/irc-instruction.txt}{IRC}. Your presence on the list/forum does not imply a commitment to answer all questions or implement all feature requests. +{\bf Communications channels}. + +IRC is good. Try \href{http://lanlab.org/course/2020s/spm/irc-instruction.txt}{IRC}. + +However, it turns out that IRC in China is not at all popular. Everyone uses QQ or WeChat, intermixing their work with their life. + +Your presence on the list/forum does not imply a commitment to answer all questions or implement all feature requests. + +{\bf Developer guidelines}. -{\bf Developer guidelines}. For potential contributors. +For potential contributors. Basic elements: \begin{itemize} @@ -1350,22 +1394,31 @@ Good examples: Contrast Developer Guidelines with Developer Documentation. -{\bf Documentation.} Essential. People need something to read about your project. Make people's +{\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 Documentation.} + +Essential. + +People need something to read about your project. Make people's lives easier. Maintain FAQs (both online and in the distribution). Provide an all-in-one page so that -people can search. Fine to be rudimentary and incomplete. The most important documentation for +people can search. Fine to be rudimentary and incomplete at first. 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}, \href{https://readthedocs.org}{Read The Docs} (an online documentation tool). Tell the readers the {\bf known deficiencies}, issues. {\bf Put everything in one page}. See things from the reader's point of view (hard). +{\bf Hosting}. -{\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.) +A website for users and a website for developers (code repo, bug tracker, +development wiki, mailing lists, etc). Two sites link to each other. -{\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. -Use canned hosting. +Not necessary in the beginning. Use canned hosting instead. {\bf Choosing a license and applying it}. |