A while a ago there was discussion about the community stalling and the state of the documentation. As far as I can remember and see, there wasn't really any agreements or solutions what to do -- so I raise the question again -- and propably aim it to the people at Zope corp., what we -- noble users -- could do to help your work on documentation?
(FWIW, as of today, I am at least nominally in charge of documentation at Zope Corporation.) At the moment, I am concentrating on improving the state of the canonical "booklike" docs (the Developer's Guide and the Zope Book). Since it's a part-time job (I'm also doing customer work), it's going to go pretty slowly. But it is going. I'd love some feedback on what I'm doing and what I plan on doing. Here's what I've done so far: - Improved the BackTalk documentation system (a system for displaying and allowing comment on booklike content) to do simple things like accept multiline comments and not break when someone comments on a (preformatted) example paragraph. See it at http://www.zope.org/Documentation/ZDG Here's what I'm working on at the moment: - Enable automatic PDF generation from booklike sets of structured text documents (ala the Zope Book). This will help form the basis for a new "canonical" documentation workflow that gets CVS out of the loop. - Make the "canonical" place for the Zope Book a BackTalk book in order to allow easy commentability. Currently the Zope Book only allows comments via a SourceForge tracker. The "canonical" version of the Zope Book is currently kept in CVS, which is not readily commentable by the average reader. - Develop a system for producing "release" documentation at each Zope release. The release documentation will be immutable and downloadable in PDF and HTML. For example, there will likely be PDFs and HTML tarballs of the DevGuide and Zope Book made for each Zope release. The "canonical" version (in BackTalk) will be culled for comments at each release and edited. Optimally, when a release is made, all the comments will be addressed and removed from the BackTalk version to start afresh. Here's stuff that I want to do: - Get the ball rolling on the Zope Administrator's Guide again. It's been stalled since last year. I am a big fan of allowing comments to booklike documentation and using those comments to improve later revisions of the documentation. This is actually pretty easy. The *real* challenge is harnessing the energy and work of the community that gets put into HowTos and ZopeLabs tips and whatnot in a canonical place. I'm not really sure how to do this. It's a big job. It requires actually sitting down and reviewing the mass of content that exists, throwing away the old cruft and keeping and categorizing the good stuff. We don't have systems in place that let us do this (or delegate this) effectively. That means that a few motivated individuals will need to bear the brunt of reviewing, editing, categorizing all existing content on Zope.org. Then a system will need to be built (or repurposed -- ZDP) that makes the process easier the second time around. ;-) Then the system needs to be used, which means it needs to be easy.
We have a great community -- that is unfortunately in very many pieces around the world. Nice thing is the diversity, but in some cases the effiency suffers. Should one turn into ZDP, Zope zen, zope newbies, zopelabs or search through the mailinglists? Huh?
Right. This is a hard problem. Good thing we're in the content management business. ;-) Some options for improving the situation right now: - try to find all the best "nuggets" in the form of HowTos and whatnot and try to fold these into the Books (ZB and DevGuide) in the form of new chapters or paragraphs. - kickstart new.zope.org. (zzzz... ;-) New.zope.org has a lot of the features that we've been wanting like workflow for docs and products, if it ever gets out.
What I am suggesting is that together we create a certain set of methods of work, that we all will follow and help others to follow. These will include some etiquette on the mailinglists, howto's and what to do with the information -- for example where to store good code snipplets etc. I know it sounds hard and would require work with many people, especially the great persons who now maintain great sites at zope.org -- but also zopezen.oeg, zopelabs.com, zopenewbies etc.
Well... sure. If you were to come up with a set of guidelines for submitting documentation snipplets, it would be great. I could then put it up on the docs page. Getting folks to follow those directions will be kinda hard, but it'd be a start.
It only requires some time and commitment -- which for most of us equals money. But count the numbers and tell me honestly, would you have any less -- or way much more, if our community for some parts would work like a well oiled machine. Atleast for me, Zope has been a great source of inspiration -- and honestly changed the way I see development... And I would be honoured to give something really valuable back.
Great! I'm up for any suggestions. Whatever we do, it needs to be reasonably low-maintenance and fairly simple (and quick) to implement. - C