discuss: LDP Style discussion (cont.)
Subject:
Re: LDP Style discussion (cont.)
From:
"Joy Y Goodreau" ####@####.####
Date:
9 Apr 2002 18:09:06 -0000
Message-Id: <OFBFE337D7.042DD0FF-ON85256B96.004C1A0A@pok.ibm.com>
Glen wrote:
>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:
That is a great idea. If you could submit a brief intro to the tags, a
scenario for when to use the tag set, the tags as an example and then real
output to the authors of the LDP Author Guide it would be great. This type
of information is covered in there with some scenarios and sample tags, but
the more concrete examples with cut and past code are so useful. I know
that when I started tagging DocBook (and even now), I was always looking
for someone who had examples of real situations and tag structures.
Maybe if other authors could take a look at the LDP Author Guide and see if
there are example gaps, then they could suggest scenarios or even offer
code. Maybe one of the LDP Author Guide authors could give some feedback
here.
>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 will be more than happy to put this on my personal "to do" list. This
seems to be a great fit for the LDP Author Guide also. Maybe as its own
section immediately following what is now called the Style Guide. Perhaps
even in that section if the section is renamed to Writing and Structuring
your Document.
>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'll check into it as part of a resource collection. The Style Guide we
use at IBM is a corporate Style Guide, which does place the burden of
enforcement on the editors. If this were the route we were going then we
would be more in line with the Gnome Style Guide. I'm not advocating this
kind of rigor. I'm not sure that our authors are ready for that much
rigorous enforcement anyway. We also don't have that many technical editors
here to handle all the docs. This doesn't mean that we can't aim for higher
quality docs, though. It may be a multi-level process.
>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.
Those 5 things are so different for different people. The guide will not be
exhausting, but it will be more than 5 things. I don't know if any of us
could be happy with only 5 things. There is more than just grammar here.
There is style issues such delivering a set of instructions. It is a very
common mistake that new writers put instructions in bulleted lists. Now, we
know (usability research and human cognition studies) that people read
bulleted lists as items that are of equal value. Dividing instructions into
numbered steps with ordinal values give readers a clear idea of action and
position within the process.
I appreciate your responses. I think you have identified some areas where
more would be great, but I don't think those things take the place of a
style guide, they do supplement good writing practices. This is the goal
after all--good documentation. Thank you for responding.
joy
Joy Yokley Goodreau
Linux Information Developer
LDP Collections Editor
Ofc. (512) 838-4118
T/L 678-4118
####@####.####
