TL; DR: To encourage contributions to developer documentation you can maintain Sphinx based documentation on GitHub, deploy it via readthedocs.org and have this nice “Edit this document” pop-up note on the deployed docs.

The source code for the edit pop-up is here. I hope you can see my cool CSS3 effects!

Also this blog post is a story how you gain 180k words worth of developer documentation almost from the scratch for your favorite Python project. A Story worth of telling, I hope.

1. History

To understand the context and the level of complexity.

Plone CMS, mature (as in your great-great-great-grand-aunt) Python based content management system, has not been very developer  friendly. The goal of “to make it easy to customize and extend” has never appeared in Plone roadmap or conference keynotes. Instead, the most of the developers have generally been busy of doing more interesting stuff and pushing the technology forward.

Plone is also geared toward more heterogeneous end of codebases out there, due to its long history (>10 years – a long time for a Python product) and adoption of many third party-ish packages in the codebase (248 Python packages) . All these packages, including critical packages you should understand for extending Plone for your own purpose, come with less or even less documentation. Sometimes packages are not Plone related and authors may not be interested how to apply the re-usable components in the context of Plone.

It’s all sucks if you are a developer and simply want to get your little customization done into Plone. You need to drill through a stack and try to guess which piece of history to apply in which point of source code.

2. From closed official documentation to open-ended unofficial documentation

There exists an official Plone developer documentation – official in the sense Plone Foundation has copyright over it. However this level of ownership, right to relicense, comes with a price: it’s “hard” to contribute for it – you need to sign a contribution agreement (by hand) and snailmail it somewhere. Due to lack of content and contributions, the official documentation does not carry you far.

Somewhere in the past “unofficial” Plone developer documentation was started. The goal of this project was to have more open-ended documentation process to get some developer documentation for Plone in the first place and the fix some of the problems mentioned before. The spirit was “wiki-style” though the tools were different. The community went through some mailing list wars about the future of the documentation. This was the future then (and now is the current past):

• First the unofficial documentation was bunch of Plone pages (WYSIWYG) managed in plone.org. We were living the time when Sphinx was still a dream in its authors minds.
• Then it was converted to reStructured Text pages, still managed in plone.org
• Then it was pulled out from plone.org, converted to Sphinx, put into Plone “collective” Subversion control (no contrib agreement needed). We were living the time when first Sphinx release was put out into PyPi.
• Sphinx becomes de facto method of creating Python developer documentation
• Then it was hosted as standalone HTML files, under collective.developermanual Python package, on random hosts
• Then it was hosted on plone.org again. This time Sphinx generated HTML was imported to plone.org using a tool called Funnelweb. Funnelweb was originally created for importing arbitary sites into Plone as Plone content (it has been known to work for Liferay, WordPress, Drupal, etc.) Howver, this was still bad idea as Funnelweb does not have really have a concept of updating docs – just one time imports and data dumps.
• And, da-da, it’s 2010s, readthedocs.org is launched. The documentation management is moved to GitHub as, with readthedocs.org, this solves the need for automatic documentation deployments after a commit.
• GitHub creates a button Fork and edit this file
• readthedocs.org gains edit back link when issue 152 is worked around
• The documentation title is renamed from Plone community maintained blaablaablaa to more simple Plone Developer Documentation (as opposite to official Plone Developer Manual)
• This blog post is written – hoping to encourage even more open-ended developer documentation contributions

Plone Developer Documentation now contains 183 792 words. It is comprehensive, but not coherent. It also crucially lacks polished, hand holding, Hello world tutorial needed to lure in new developers (someone please take a ball on this). Even with these little hindrances, based on the readers’ comments, it’s slowly becoming really really good.

The unofficial documentation is licensed under GPL license. The rationale for this is simply the fact that when collective.developermanual package was created this was the default license coming in Paster templates. Also, Plone Foundation’s official stance is that when you import code from Plone your product should be GPL. The documentation contains a lot of code starting with import plone… This little gem does not have any practical impact, but I wish to live to see some arguments about this.

3. Fork and edit this file

I love GitHub; I hate Git. Git is the anti-thesis of user interfaces – what a version control system would look like if it were developed by persons knowing only C and Perl and who’d love to scare away all other developers how are not equally smart. But luckily with GitHub, everyone, even without theoretical version management course studies, can work with Git.

One of GitHub’s recent innovations is Fork and edit this file button. It allows anyone to suggest changes to source file. No prior relationship between the author and the contributor is needed – the suggestion goes to the pull request queue and you’ll get a notification about the contribution.

This was a holy grail for me who cares less about politics and more about getting in more contributions.

• Any person can edit the file, as Git/SVN checkout is not needed
• You don’t need to maintain user list of “authored editors”
• The GitHub editor itself (ACE based?) is actually nice: selecting text and hitting Tab key actually indents a block of text. It’s way beyond crappy <TEXTAREA>.
• You get pull request notifications
• You can post-edit proposed changes easily and communicate with the contributor

4.  Linking it back

A perfect documentation update workflow would be that when you want to edit a piece of text you simply click it in the place, edit in place and press Save. This is what Wikipedia was before it grew too large.

With readthedocs.org, GitHub and Javascript  magic we cannot reach such fidelity yet. We

• Don’t know if user is logged into GitHub, or his/her GitHub username
• Cannot edit individual Sphinx paragraphs in ACE
• Don’t have GitHub Javascript API to push in commits/pull requets

(Please correct me if I am wrong)

But someday we’ll be there.

Meanwhile, we have something what we call in Finnish a “fur cap solution” (karvalakkiratkaisu). It means solving the problem in the least complex way, but still achieving the solution somehow. (If someone would like to clarify the etymology of this proverb or has a translation for it I’d like to hear that also)

In Sphinx HTML templates we simply include backlinks to the source code file on GitHub and have bulleted instructions how to edit the file:

5. Future future

After struggling several years of getting any developer documentation for Plone I am think I am finally quite happy and my work here is done. It’s not perfect, but compared to other CMS’s we are not definitely the worst anymore.

What still is needed is more interactivity – where people can ask questions in the context of documentation, like happens on php.net API documentation. Then store the question and the answer in the context, so the future generations do not need to wonder the same thing again. This far I have been manually linking stackoverflow.com questions direcly to the documentation when I am too lazy busy to start writing anything. Sadly, the orignal plone.org documentation had discussion feature until it was disabled, due to lack of good notification system. Maybe we could do something akin the lines using DISQUS and Sphinx and post questions to the mailing list?

6. Ps.

The edit pop-up note text, due to CSS3 rotation, looks like crap on Firefox 10 / OSX. Chrome does not suffer from this. A bug in FF text rendering?

 

 

 

 

 Subscribe to RSS feed Follow me on Twitter Follow me on Facebook Follow me Google+