Open source project documentation on Github and readthedocs.org

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

Sphinx based documentation is now hosted on Github
The documentation is open-for-all editable through Github inline text editor (ACE)
The documentation is deployed on readthedocs.org
We have edit backlinks in the documentation and try to encourage contributions

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

$\"\"$ Subscribe to RSS feed 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”

Jörgen Modin on 2012-07-26 at 15:17 said:

Thanks for the Plone Developer Documentation. It is really good!
Nick Coghlan on 2012-07-26 at 15:31 said:

Interesting info – and I’d suggest simply “automatic publication” to describe the RTFD+VCS hooks setup.
Chris Crownhart on 2012-07-26 at 19:27 said:

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.
Christian Ledermann on 2012-07-26 at 20:59 said:

What about operating systems? Firefox + chrome > 85% maybe there is a suprise in OSs as well
Mikko Ohtamaa on 2012-07-27 at 10:28 said:

@Christian: Added operating systems. Very interesting in fact 🙂
Christian Ledermann on 2012-07-27 at 10:55 said:

“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

Open Source Hacker

Pushing the boundaries of free technology

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

1. Some stats

2. Lessons learnt

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

Leave a Reply Cancel reply