Open source project documentation on Github and readthedocs.org – a year later

After having Plone CMS‘s   Plone Developer Documentation (collective.developermanual project) hosted on Github a year or so how do we fare?

1. Some stats

  • 45 contributors
  • At least one commit per week
  • The most popular of Plone community repositories (plone + collective). Plone community has more than 400 repositories on Github alone.

Six month progress – no clear visitor growth :( (background: Plone does not compete with WordPress et. al. as it mainly solves “big intranet” problems which are not that common)

People don’t work during weekends.

Google, plone.org and stackoverflow.com bring us the visitors.

Troubleshooting is pretty popular with Plone… :(

Plone is utterly popular in Brazil.

Long live Firefox. As a side-note Alexander Limi, the guy who did the original praised design of Plone UI, does Firefox UI design nowadays.

We must be attracting a lot of non-Plone developers, because everyone knows Plone developers run OSX or Linux… and who confesses to be this FreeBSD guy?

2. Lessons learnt

  • Plone, Zope and buildout should give better error messages so people would not need to visit troubleshooting sections
  • Better Hello world tutorials still needed (this is not based on analytics, but the sad state of the authors…)
  • readthedocs.org and continuous documentation deployment (is there official term akin continuous integration) kicks ass – you can forget the documentation release process, because it is so automatic and just works
  • Edit backlinks in the documentation have proven to be succesful. When you are reading the documentation you can fix the errors in the matter of seconds. Github’s web editor gives wiki-like pace.
  • Github’s fork and edit even better than wiki as non-core editors will generate pull requests and you have a tool and a process to manage those changes

Ps. Also read this interesting reddit thread about history of Plone, Zope and Python

Buy open source friendly bitcoins  Subscribe to this blog in a reader Follow me on Twitter Follow me on Facebook Follow me Google+

6 thoughts on “Open source project documentation on Github and readthedocs.org – a year later

  1. Interesting info – and I’d suggest simply “automatic publication” to describe the RTFD+VCS hooks setup.

  2. Thanks for taking time to collect and post these graphs. Always interesting to see how documentation is used. The Developer Documentation is invaluable — we use it all the time.

  3. What about operating systems? Firefox + chrome > 85% maybe there is a suprise in OSs as well

  4. “We must be attracting a lot of non-Plone developers, because everyone knows Plone developers run OSX or Linux”

    I would not jump to this conclusion. In videos from past plone conferences it is not unusual to see presentations given on MS Windows. But it surely shows that Linux and OSX are very popular desktop OSs for plone developers

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>