[Zope-CMF] Suggestion - Modular Documentation

[seb bacon]

( use StructuredTextNG, not HTML ... )

I think a doc-as-you-go standard is a very good idea.  You're thinking
of users *and* developers, right?  The requirements are very different
for these groups.  For developers, the most important documentation
apart from the source (including, preferably, interfaces and nice
comments) would probably be an API for the tools / services - which
should be plugged into the Overview tab.

For users, since at least half of user documentation is related to the
UI, the correct place for help is with each skin.  I'm not sure how
reuseable help would be between skins.  Do you have any examples in
mind to demonstrate how you think it might work?

In principle it's an excellent idea, but requires a lot of discipline
by developers and simple, strong, easy to follow documentation
guidelines / APIs, and a lot of metawork - in other words, someone to
drive it who's got quite a lot of spare time.  I think this has been a
problem with ZDP quite often.

seb

* Jon Edwards <jon@pcgs.freeserve.co.uk> [010704 15:03]:
> 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
> 
> 
> _______________________________________________
> Zope-CMF maillist  -  Zope-CMF@zope.org
> http://lists.zope.org/mailman/listinfo/zope-cmf
> 
> See http://www.zope.org/Products/PTK/Tracker for bug reports and feature requests

-- 

   [] j a m k i t 
           
        seb bacon
T:  020 7749 7218
F:  020 7739 8683
M:  07968 301 336
W: www.jamkit.com