[Plone-docs] New approach - summary

[Alexander L. <li...@pl...>]

OK, spoke to Andy on IRC, and we agreed that CVS is the way forward. I need 
to clarify a couple of things that have caused some confusion. After 48 
hours without sleep, I'm not as eloquent as I'd like to be, it seems ;)

Andy wrote:
>> Um. This happened with Zope and I'm not sure its a good long term plan,
>> the online help for Zope became the book. And I think in many ways it
>> tried to hit two targets and missed. Documentation requirements change
>> for different areas and different audiences.

I wrote:
> Not the same at all. Zope had horrible pop-up-things with trees that 
> emulated Windows95

What I was trying to say is that plone_help is just an additional place of 
having the books. It's *not* meant to be context-sensitive help. Just an 
"offline" (that is, without internet connection necessary) version of the 
documentation that is searchable via the Plone interface.

>> My plan was to ship a PDF (or a CHM for Windows) with the Installers,
>> that contained the book.
>
> Should be easy with the reSTX-to-PDF scripts.

...and what I was trying to say: We do them all. Horses for courses, or how 
that strange English expression goes ;)

Different people, different habits.

I wrote:

> When our content management system's versioning sucks, we have to do 
> something else for a while. We have a problem, and we've seen that 
> authoring this stuff in Plone doesn't cut it right now. We are not a 
> document management system just yet.

This is my main important point. We are growing way too fast, and 
documentation can't keep up if we depend on third-parties doing most of the 
documentation via a web-based interface. We, the developers, need to get 
down and dirty with the code. We shouldn't fool ourselves into thinking 
anything else will work.

However, what we *need* "outside people" to do is

a) clean up docs (coders write like %¤" when they are in a hurry, and we 
always are ;)
b) make sure the documentation is consistent and approachable
c) point out holes they cannot fill in themselves
d) make sure the index (content listing) is up to date

I also wrote:

> You are mixing book format with bite-sized things here. One topic should 
> be one document, IMO. Installing Plone on Linux is a separate document 
> from Installing Plone on Windows. They are both in the Installing Plone 
> folder.

This is still important. Folders and logically named, bite-sized files are 
very easy to handle and rearrange. We can keep a separate index for the 
different output types, if needed - but I assume one will do.

As a summary, I wrote:

> - We get proper versioning
> - People can use their tools of choice with a minimum of hassle
> - Proper undo/rolback
> - Good history
> - Language branches.
> - Multi-format (PDF, web, Plone-instance).
> - Separation of comments and content.
> - Diffing.
> - Notification via mail when something has been updated.

This still stands.

> All reasons why Plone as a project has blossomed. Taking as many of these 
> principles and applying them to the documentation process makes sense - 
> not least because we need to get away from the utopic thought that 
> programmers and designers don't write documentation. They need to, and 
> this lowers the threshold *drastically*. If I can just update the text 
> file in my CVS repository every time I make a change that affects the 
> behaviour of Plone, it's much more probable that I will do that change, 
> and commit it with my code.

The final thing we agreed on via IRC was that we need to *enforce* 
documentation. By moving it to CVS, you have no excuse of not updating the 
relevant documentation when you do something.

And, let's face it - documentation is more fun than unit tests ;)

There's a hidden (not very well hidden I admit, more like me trying to hide 
behind a cup of tea :P) truth here:

Documentation is Unit Tests for User Interfaces.

And I'm going to take the responsibility that goes with that, and document 
the interface. I will wear the "I suck" t-shirt if I don't. Plone's 
usability should not suffer from bad documentation.

I expect no less from our coders. Document API changes, new modules, 
strange behaviour.

We can do this. And I am so tired I'm almost collapsing here (maybe that's 
why I am so convinced We Will Triumph ;)



-- Alexander Limi
   http://limi.net
   http://plone.org