docs (was: Re: Microtype in ConTeXt)

[Michael Saunders <odradek5@gmail.com>]

Peter, that post of Hans's mainly argues that the old manual is good
enough and then goes on to talk about development.  For example:

"Even an old manual can quite well describe functionality as much
didn't change."

It can if it ever did.  I don't think cont-eni.pdf etc., describe the
functionality well at all.

"As one can visually get all kind of output and as
typographical elements can interfere the ultimate manual would
show $n!$ variants and become quite unreadable. There is no easy
way out of this. "

There is:  describe each option concisely and abstractly, then you
need only be concerned with $n$ elements.  Almost every LaTeX package
manages to do this successfully, and they are very usable.

"More documentation would not help all users. "

There needn't be more.  It needn't be lengthy, just clear, complete,
and concise.

"There are quite some options that were never meant for
usage beyond our own, but as we ship the full product, they become
visible. No, they are not documented apart from the source. Yes,
if useful they should be documented but why by me? "

Because you are probably the only person on earth who understands
them.  Getting that knowledge out of your head and into others' will
require an act of communication.

"I only work on a manual (or article or whatever) if it's fun to do."

That may be the problem!

Hans, Here are some constructive suggestions.  I hope you take them seriously:

If you ever write another manual, perhaps when MKIV is complete,

1.  Start from scratch.  Throw away the old material.

2.  Forbid yourself the use of code examples.  They are a crutch which
impedes communication.  First, write the whole manual with normal,
abstract, expository prose.  When it's complete and explains
everything fully---when it {\em makes sense}--- {\em then} illustrate
it with as many code samples as you like.

3.  Have a standard format, a sort of checklist, for what must be said
about each argument, parameter, command and group of commands:
---What is its function?
---How is it used?
---What is it used for (what effect is it supposed to achieve)?
---What are the options?
A regular format like this will make it much easier on you.  You'll
have a regular structure that you simply have to fill in.  It might
even make the task more fun.

4.  Get someone to serve as an editor.

These will solve most of your writing problems.  I look forward to a
new manual someday.

Thanks,

-- Michael
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://tex.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________