How do you prefer your documentation?

Lately there have been three long email chains related to Plone development documentation here, here and here (total ~100 messages). This little post tries to summarize the current discussion.

I think the dicussion is mostly fueled by third party developers’ frustration with the current development documentation situation. Developing for Plone is difficult, since finding references, how tos and examples for those little things you need is very hard. This is a turn off for many developers who would otherwise use this great system – high developer learning curve and gaps in the documentation makes the system useless.

Points everyone agree are

  • Plone development documentation is not good
  • Sphinx is good for API documentation – already happening
  • Contributors are needed

Points discussed are

  • Should developer documentation be more open ended (Wiki-like). This covers
    • Developer manual
    • How tos and other misc. references
    • API documentation
  • Mostly, it is not about generic end user, admin or system integrator or getting started documentation (here, here)

Pro wiki-like documentation stances

  • It should be more open ended (here, here, here)
  • It’s better to have something messy instead of nothing at all – the current approval process discourages contribution (here)

Con wiki stances

  • It should not be open ended, since this results to messy documentation (here, here)
  • There should be less documents (here)
  • Wikis are bad (here)
  • Incomplete wikis are discouraging (here)

Let’s wait and see where this goes.

5 thoughts on “How do you prefer your documentation?

  1. Thank you *very* much for the summary. I haven’t had the time to follow all those threads in detail 🙂

  2. Ditto and +1. I’ve tried following the documentation conversation, but fell behind and then was able to read only a couple of the message digests thereafter. I’m interested in contributing, once I have more Plone under my belt.

    I’m in the anti-wiki camp, for documentation. Instances of wikis being used successfully for technology documentation seem to be due to accidental luck more than anything else. 🙂

  3. +1 for this post and I’m a volunteer to work on a Sphinx powered book for developers/integrators.

    I’m an anti Wiki for that kind of documentation. collective Wiki documents lead to a real mess as such tool does not foster a consistent structure.

    In addition, Sphinx may handles automatically the API documentation. Not a wiki.

    On any doubt on what can be done with Sphinx, have a look at the Sphinx based – excellent – developer documentation that ships with Django 2.1.

Leave a Reply

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