discuss: LDP Style discussion (cont.)
Subject:
Re: LDP Style discussion (cont.)
From:
Glen Turner ####@####.####
Date:
9 Apr 2002 01:13:35 -0000
Message-Id: <Pine.LNX.4.44.0204091010040.1519-100000@bush.aarnet.adelaide.edu.au>
I'd like to see:
1) Complete DocBook code for common constructs
Let's take a standard command line interface session. What
I want is something I can cut and paste and which works
in a non-toy document. For example, a CLI command and
response template would be:
<figure id="*SECTION-TITLE*">
<title>*TITLE*</title>
<screen format="linespecific">
<prompt>bash$</prompt> <userinput>*COMMAND1*</userinput>
<computeroutput>
<![ CDATA [
*OUTPUT1*
]]>
</computeroutput>
<prompt>bash$</prompt> <userinput>*COMMAND2*</userinput>
<computeroutput>
<![ CDATA [
*OUTPUT2*
]]>
</computeroutput>
</screen>
</figure>
Even this monstrosity has gotchas (try the command "ls > example.txt").
This is amazingly non-obvious to a DocBook beginner. Working out all this
formatting structure gets seriously in the way of actually writing the
document.
The DocBook code also needs to relate to the standard document structure,
the exmaple above enforces the guideline that each illustration should
have a title.
2) A guide to structuring documents.
How to explain a concept. eg:
- begin new section
- link to previous section
- describe the whole
- for each concept
- give an overview how this concept fits the whole
- give a specification
- detail the concept, refering to the specification
- give an example of the concept (eg: a config extract)
- describe issues arising from the example
- itemise exceptions
- give an example of the whole (eg: a complete configuration
from a real distribution)
- itemise bugs and gotchas
- end section
- review description of the whole
- link to next concept and section
And similarly for questions like "what should be in an introduction".
Granted that this short of checklist cannot be absolute, but supplying one
is a great aid for poor writers.
I've written books for Macmillan and IBM and both had this sort of author
aid, which the copy editors rigorously enforced. Given IBM's support for
Linux in general it may be worthwhile asking them to contribute their
author guide to the LDP.
I'm not sure that I would be too concerned about English usage. Good
structure and examples can do a lot to make up for poor expression -- I've
worked from manuals in Japanese and German and good documentation was
usable with about 5% of it translated (mainly the gotchas). It's also
easier to fix poor expression, as this requires little specialist
computing knowledge. Fixing an inconsistent set of examples requires
specialist work.
I'd encourage any guide to English usage to limit itself to, say, the five
things that would most improve writing. It's unreasonable to expect a
once-only author to remember any more style items than this when writing
their first piece of major documentation.
Regards, glen
