Re: [groff] mom manpage

[Ingo Schwarze]

Hi Peter,

if you are interested in my perspective - scrap the HTML documentation
and fix the manpage.  The reference manual - i.e. the manpage - is
really important: when you use some software regularly, you use the
reference manual all your life.  Catering to the experienced user
is most important because whoever is serious about using the software
will become experienced sooner rather than later.  So the reference
manual (manpage) must be concise, precise, and correct.

If an author has too much time on his hands and doesn't doesn't know
what to do with it, there is nothing wrong with writing a beginner's
tutorial, too.  But it's really not so important.  You skim through
that once, than quickly move on to the real thing for further learning,
often even before finishing the tutorial.  And then there is never a
need to come back to it, so it doesn't really matter that much - "use
once" is much less important than "use always".

Besides, even beginners can easily learn from a well-written reference
manual.

Hell, *especially* when i know nothing about a software and just
need to use it quickly for one task, i invariable go straight for
the reference manual because the relevant bits are almost always
less text to read in the ref docs than whatever "user manual" or
"tutorial" there may be, so reading them takes less time there.

Write the real manual in some other format than a manpage?  Bad
idea.  it means you make it harder to access, out of the usual place
where people look for documentation, in a gratuitiously different
format.  You want HTML and PDF versions?  Not a problem at all with
manpages, after all, typesetting is what Jerry Saltzer originally
designed RUNOFF for.  You want hyperlinking?  Not a problem with
.Xr links in modern manual pages either.  You want bells, whistles,
and moving gifs of cute cats?  Bad idea, documentation is about
efficiently conveying information, not about fluff and pictures
and gimmicks.

You want to exercise the language itself in documenting it?  Bad
idea, the documentation is about concisely and simply explaining the
syntax and semantics, and that doesn't require writing the
explanation in the language itself.  C library manuals are not
written in C - but they can contain concise examples of C code
in the EXAMPLES section, near the end.  Same for mom.

Even moderately large systems can be beautifully documented in a
single manual page - for example, a shell.  If is system is too
large and a single page would become unwieldy, yes, in the first
step, you split it up to the next logical level - i guess for mom
that would be macros, but you can probably judge better than i can
what that next level is.  That gives you too many pages, most of
them unreasonably short?  So you form logical groups of related
macros, make one page for each group, and name the page after the
most important or typical macro of the group.  That page can also
- concisely! - explain the basic concepts relating to that group.
Practically all library manuals (section 3) work exactly that way.

This is not rocket science and nothing new - just do it...  ;-)

Yours,
  Ingo