[Zope-CMF] Suggestion - Modular Documentation

[Jon Edwards]

> ( use StructuredTextNG, not HTML ... )

<mini-rant>

bleeeucccch!! Am I the only person in the world who doesn't "get"
Structured-Text? (That was a rhetorical question, *please* don't answer it!
I know it's just laziness on my part!) ;-)

</mini-rant>

> I think a doc-as-you-go standard is a very good idea.  You're thinking
> of users *and* developers, right?

Well, I'm thinking of users. I wouldn't feel even slightly qualified to
produce docs for developers, but if a similar approach would work for them,
that's a bonus.

But I know that, sooner or later, I'm going to have to write training-notes
and user-manuals for our customers, so that was my motivation.

> 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.

Actually, I think there are three "audiences" for CMF, each of which needs
their own documentation (and this kinda links back to last week's discussion
about how to market the CMF against more commercial competitors) -

1. Developers - a wide range, but I would *very* broadly define this as
"most people who subscribe to this list" - people who are going to use DTML
and/or Python to customise CMF.

2. Integrators (there must be a better word for this?) - people in the IT
departments of the SMEs mentioned last week, who are looking for an "instant
intranet" and need to know how to install and do some basic
customisation/setup, without needing to learn any DTML/Python. (They also
want to find some docs to print out for their users - if these docs are
easily customisable by anyone with a basic knowledge of HTML/CSS, so much
the better).

3. End-users - the "customers" of groups 1 and 2. From bitter experience, I
know that these people have a congenital allergy to F1/Help keys! You have
to give them dead-trees!

> 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?

I think you're right, the skin-level is the perfect way to divide
documentation into "chunks".

So, for example, there's a help-doc for the folder-contents screen. If your
product uses folder_contents "as is", you have a readymade page for your
manual. If you customise folder_contents, you customise the help-doc to
match. If you're distributing your product to a wider audience, you include
your customised help-doc in the package.

> In principle it's an excellent idea, but requires a lot of discipline
> by developers

It would be very much a "voluntary standard" - if you're producing a product
that you hope will be used widely, it's in your interests to use the
standard, as it means less work for you to produce user-documentation, and
it means your documentation is easy for the Integrators to slot into the
"CMF Manual" for their end-users.

> 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.

Well, I think perhaps it's the sort of thing someone at DC should "own", if
they think it's a good idea? But, as I said, at some point I'm gonna have to
do user-docs (and there must be other people in a similar situation?), so
I'd be happy to contribute.

Hope that makes sense?

Cheers, Jon