[Zope-CMF] Suggestion - Modular Documentation

[Jon Edwards]

I have a half-baked idea - Modular Documentation for the CMF and CMF-related
products.

The best comparison would be with the help-pages that are included with some
Zope products (except we're aiming the docs at end-users, not Zopers).

So, new/existing documentation is broken down into bite-sized chunks of
low-level html text - nothing more complicated than a <h2> or <strong> tag
allowed, in fact the community could define a set of "permitted tags"
(though we might need something fancier to allow screenshots to be
included?). We could also define standard formats for a help-doc, e.g. each
doc should have, header, intro, explanation of each function, page headers
should be <h2>, section headers should be <h3>, and so on?

Producers of CMF-products, or people training end-users, then have a range
of readymade doc fragments (to which they add their own, for their specific
needs) which they can bundle together, apply their own stylesheet and
pageheaders/footers, and hey-presto, a user manual!

If I use some of Swishdot's functionality in one of my projects, I just take
the doc-fragments for the Swishdot functions I'm using and bundle them up
with the bits I need from other products, as above.

When some functionality changes, only a small amount of documentation needs
to be altered and reprinted/redistributed.

I think this is similar to what the ZDP aimed to achieve? It'd be
interesting to find out why they didn't get a better uptake. It may be that
the modular/plug-n-play nature of CMF is better suited to this approach?
There's more incentive for people producing products to use the standard, as
they gain by being able to use all the other readymade docs in their own
user-manual?

Does that sound bakeable? :-)

Cheers, Jon