mirror of https://github.com/tLDP/LDP
445 lines
15 KiB
Plaintext
445 lines
15 KiB
Plaintext
|
|
<chapter id="styleguide">
|
|
<title>LDP Style Guide</title>
|
|
|
|
<sect1 id="sg-subject">
|
|
<title>Deciding on a Subject</title>
|
|
|
|
<para>
|
|
Before you begin writing a HOWTO, it is essential that
|
|
you determine what subject area you will cover. It is best if the
|
|
subject area is:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Not too broad, and not too narrow.</title>
|
|
<para>
|
|
Try to cover too much information,
|
|
and you may sacrifice depth. It is better to cover a
|
|
small subject area fully than to cover a large subject
|
|
area poorly.
|
|
Linux tools are known for doing exactly one
|
|
thing and doing that one thing <emphasis>well</emphasis>.
|
|
Similarly, your HOWTO should cover one subject and cover it
|
|
<emphasis>well</emphasis>.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<para>
|
|
If your subject matter is very small, it might be better
|
|
included as part of another HOWTO. This makes it easier
|
|
for readers to find the HOWTO they need. Search the LDP repository
|
|
for HOWTOs on related topics, and see if you could place
|
|
your information in an existing HOWTO.
|
|
</para>
|
|
|
|
<para>
|
|
How much is too much?
|
|
How little is too little? That depends on the subject
|
|
you chose, your mastery of that subject, and many other
|
|
factors. Just keep this admonition in mind, and use good judgement.
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Clearly defined.</title>
|
|
|
|
<para>
|
|
Know before you begin exactly where the boundaries of your
|
|
subject area lie. You should not cover the same ground as another
|
|
HOWTO, and you should try not to leave gaps between your HOWTO
|
|
and related HOWTOs, either.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Undocumented</title>
|
|
|
|
<para>
|
|
Before writing on a particular subject, check other HOWTOs at the LDP,
|
|
and see if the topic is already documented. If it is, refer to the
|
|
other HOWTO instead of rewriting documentation that already exists.
|
|
Don't reinvent the wheel.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<para>
|
|
If the HOWTO already in place is insufficient, or needs updating,
|
|
contact the author and offer to help. LDP authors are usually nice folks.
|
|
After all, they put in their own valuable time to help people they
|
|
don't even know. And, they appreciate your help. But, please, don't
|
|
duplicate work. It causes confusion for everyone.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Pre-approved by the LDP</title>
|
|
|
|
<para>
|
|
Before you proceed with your HOWTO, post to the ldp-discuss list
|
|
and get some feedback from other LDP volunteers. Checking with the
|
|
list <emphasis>before</emphasis> you begin can save you headaches
|
|
<emphasis>later</emphasis>.
|
|
The author speaks from experience.
|
|
</para>
|
|
|
|
</formalpara>
|
|
|
|
<para>
|
|
It is a really good idea to join the ldp-discuss list, and follow
|
|
it regularly, even if you never post. It's a good way to stay current
|
|
on the activities, needs, and policies of the LDP. Although the LDP
|
|
volunteers are here to assist you, it is ultimately your
|
|
responsibility to learn these policies, and to follow them.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="sg-outline">
|
|
<title>Developing an Outline</title>
|
|
|
|
<para>
|
|
Before you actually begin writing, prepare an outline.
|
|
An outline will help you get a clear picture of the subject matter,
|
|
and allow you to concentrate on one small part of the HOWTO
|
|
at a time.
|
|
</para>
|
|
|
|
<para>
|
|
Unless your HOWTO is exceptionally small, your outline will probably
|
|
be multilevel.
|
|
When developing a multilevel outline, the top level should contain general
|
|
subject areas, and sub-headings should be more detailed and specific.
|
|
Look at each level of your outline independently,
|
|
and make sure it covers all key areas of the subject matter. Sub-headings
|
|
should cover all key areas of the heading under which they fall.
|
|
</para>
|
|
|
|
<para>
|
|
Each item in your outline should logically follow the item before it,
|
|
and lead into the item it precedes. For example, a HOWTO about a particular
|
|
program shouldn't have a section on <emphasis>configuration</emphasis>
|
|
before one on <emphasis>installation</emphasis>.
|
|
</para>
|
|
|
|
<para>
|
|
When you are comfortable with your outline, look over it once more,
|
|
with a critical eye. Have you covered every relevant topic in
|
|
sufficient detail? Have you wandered beyond the scope of the HOWTO?
|
|
You might want to show it to someone else, and ask for feedback.
|
|
It's much easier to reorganize your
|
|
HOWTO at the outline stage than it will be later. Consider submitting
|
|
the outline to the ldp-discuss list for more feedback.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
You might have noticed a theme developing here.
|
|
Just like Free software, Free documentation is best when you
|
|
<quote>release early, release often.</quote> The ldp-discuss list includes
|
|
many experienced LDP authors, and you would be wise to seek their
|
|
advice when making decisions about your HOWTO.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
Remember Linus' Law:
|
|
</para>
|
|
|
|
<blockquote><attribution>Eric S. Raymond</attribution>
|
|
<para>
|
|
<quote>Given enough eyeballs, all [typos] are shallow.</quote>
|
|
</para>
|
|
</blockquote>
|
|
|
|
<para>
|
|
(With apologies to Mr. Raymond.)
|
|
</para>
|
|
|
|
<para>
|
|
FIXME: Need a reference to the "standard" HOWTO layout, for
|
|
topic areas such as Credits, License, Copyright, etc., etc.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="sg-writingstyle">
|
|
<title>Writing the Text</title>
|
|
|
|
<para>
|
|
At this point, your HOWTO has been organized, and bits of raw information
|
|
have been collected, documented, and inserted into the outline.
|
|
Good news: You're past the
|
|
midpoint; it's all downhill from here.
|
|
</para>
|
|
|
|
<para>
|
|
Your next challenge is to
|
|
massage all of the raw data you've collected into a readable,
|
|
entertaining, and understandable whole.
|
|
</para>
|
|
|
|
<para>
|
|
It has taken quite a bit of work to get to the point where you can
|
|
actually start writing, hasn't it? Well, the hard work begins to pay
|
|
off for you now. At this stage, you can begin to really use your
|
|
imagination and creativity to communicate this heap of dry,
|
|
boring information in
|
|
your own unique way.
|
|
</para>
|
|
|
|
<para>
|
|
It is beyond the scope of this document to provide a comprehensive
|
|
guide to effective writing, so I won't try to go beyond the basics.
|
|
|
|
In the <quote><link linkend="sg-references" endterm="sg-references.title"></link></quote>
|
|
section, you will find a list of resources that cover the subject
|
|
better than this guide could hope to. Consult them, and follow their
|
|
advice.
|
|
</para>
|
|
|
|
<para>
|
|
For starters, here is some good advice from
|
|
<ulink url="http://www.resort.com/~prime8/Orwell/patee.html"><citetitle>Politics and the English Language</citetitle></ulink>:
|
|
</para>
|
|
|
|
<blockquote>
|
|
<attribution>George Orwell</attribution>
|
|
|
|
<para>
|
|
A scrupulous writer, in every sentence that he writes, will ask himself
|
|
at least four questions, thus:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
What am I trying to say?
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
What words will express it?
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
What image or idiom will make it clearer?
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Is this image fresh enough to have an effect?
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
And he will probably ask himself two more:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Could I put it more shortly?
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Have I said anything that is avoidably ugly?
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
...One can often be in doubt about the effect of a word or phrase,
|
|
and one needs rules that one can rely on when instinct fails.
|
|
I think the following rules will cover most cases:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Never use a long word where a short one will do.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
If it is possible to cut a word out, always cut it out.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Never use the passive where you can use the active.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Never use a foreign phrase, a scientific word,
|
|
or a jargon word if you can think
|
|
of an everyday English equivalent.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Break any of these rules sooner than say anything outright barbarous.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</blockquote>
|
|
|
|
<para>
|
|
And, from a purely stylistic point of view, I believe that
|
|
the first-person perspective of many HOWTOs adds to their charm,
|
|
an attribute most documentation in other forms sorely lacks.
|
|
Don't be afraid to speak for yourself, use the word <quote>I</quote>,
|
|
or describe personal experiences and opinions.
|
|
</para>
|
|
|
|
<para>
|
|
If it hasn't become painfully obvious yet, the underlying principle
|
|
of all these suggestions is simplicity.
|
|
Your readers are already struggling with new concepts, so don't
|
|
make them struggle to understand your language.
|
|
Remember the <acronym>KISS</acronym> principle: Keep It Simple, Stupid!
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="sg-editing">
|
|
<title>Editing and Proofing the Text</title>
|
|
|
|
<para>
|
|
Once you've written the text of your HOWTO, it is time to polish
|
|
and refine it. Good editing can make the difference between a good
|
|
HOWTO and a great one.
|
|
</para>
|
|
|
|
<para>
|
|
One of the goals of editing is to remove extraneous material that
|
|
has crept its way into your document.
|
|
You should go through your HOWTO carefully, and ruthlessly
|
|
delete anything that doesn't contribute to the reader's understanding
|
|
of the subject matter. It is natural for writers to go off on tangents
|
|
while in the process of writing. This is the time to correct that.
|
|
</para>
|
|
|
|
<para>
|
|
When editing and proofing your work, you must check for obvious mistakes,
|
|
such as spelling errors and typos.
|
|
However, you should check for deeper, but
|
|
less obvious errors as well, such as <quote>holes</quote> in the
|
|
information. Make sure that the contents of every section match
|
|
the title of that section precisely.
|
|
</para>
|
|
|
|
<para>
|
|
When you are completely satisfied with the quality and accuracy of
|
|
your work, forward it to someone else for third-party proofing.
|
|
You will be too close to the work to see fundamental flaws.
|
|
</para>
|
|
|
|
<para>
|
|
In a sense, editing is like code review in software development.
|
|
Having a programmer review their own code doesn't make much sense,
|
|
does it? Why does having a writer edit their own document make
|
|
any more sense?
|
|
So, recruit a friend, or write the
|
|
ldp-discuss list to find a volunteer to proofread before submitting
|
|
your HOWTO.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
If you are writing in a language in which you are not fluent,
|
|
I strongly recommend that you seek an editor who is. Technical
|
|
documentation, more than any other type of writing, must use
|
|
extremely precise grammar and vocabulary. Misuse of the language,
|
|
no matter how understandable and unintended, makes your HOWTO
|
|
less valuable.
|
|
</para>
|
|
</note>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="sg-maintaining">
|
|
<title>Maintaining Your HOWTO</title>
|
|
|
|
<para>
|
|
Just because your HOWTO has now been published doesn't mean your
|
|
job is done. HOWTOs need regular maintenance, to make sure they
|
|
are up to date, and to improve them in response to readers' ideas
|
|
and suggestions. A HOWTO is a living, growing body of knowledge,
|
|
not just a publish-and-forget-it static document.
|
|
</para>
|
|
|
|
<para>
|
|
You put your email address in the HOWTO, and politely requested
|
|
feedback from your readers, right? Once you are officially published,
|
|
you will begin to receive notes with suggestions. Some will be
|
|
very valuable; others will request personal assistance. You should
|
|
feel free to decline personal assistance if you cannot spare the
|
|
time. Writing a HOWTO for the LDP doesn't commit you to a lifetime
|
|
of free support for anyone on the net. It is polite to refer
|
|
questioners to another resource, if you can. And, if you see a
|
|
pattern in the questions you receive, it might indicate a topic
|
|
you should add to your HOWTO.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="sg-references">
|
|
<title id="sg-references.title">References</title>
|
|
|
|
<para>
|
|
There are many guides to writing style available online.
|
|
Here is a brief list of some of the best:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.resort.com/~prime8/Orwell/patee.html"><citetitle>Politics and the English Language</citetitle></ulink>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://bartleby.com/141"><citetitle>Elements of Style</citetitle></ulink>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
FIXME: Please send the URL of your favorite resource on technical writing.
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|