mirror of https://github.com/tLDP/LDP
290 lines
12 KiB
XML
290 lines
12 KiB
XML
<!--
|
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
|
-->
|
|
<chapter id="write">
|
|
<title>Write</title>
|
|
|
|
<section id="sg-writingstyle">
|
|
<title>Writing the Text</title>
|
|
|
|
<para>
|
|
By now you should have organized your document; you collected bits of raw information
|
|
and inserted them into the outline.
|
|
Your next challenge is to massage all of the raw data you've collected
|
|
into a readable, entertaining and understandable whole. If you are
|
|
working from an existing document make sure any new pieces of
|
|
information are in the best possible places.
|
|
</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 information.
|
|
Don't be too clever though! Your readers are already struggling with
|
|
new concepts--do not make them struggle to understand your language
|
|
as well.
|
|
</para>
|
|
|
|
<para>
|
|
There are a number of classic guides to writing--many
|
|
of which are available on-line.
|
|
Their language will
|
|
seem old, but the messages are still valuable to authors today.
|
|
These are listed in <xref linkend="ref-techwriting" />. Also listed in the
|
|
resources section are a variety of sites that have
|
|
information specific to technical writing.
|
|
</para>
|
|
|
|
<para>
|
|
The Author Guide wouldn't be complete without
|
|
mentioning the Plain Language movement. Although
|
|
directed at simplifying government documents, <ulink
|
|
url="http://www.blm.gov/nhp/NPR/pe_toc.html">Writing user-friendly
|
|
documents</ulink> is quite useful. It includes before and after
|
|
writing samples. There's also a
|
|
<ulink
|
|
url="http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html">PlainTrain
|
|
writing tutorial</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
And any document that discusses writing for the web wouldn't be complete without
|
|
a nod toward <ulink url="http://www.useit.com">useit.com</ulink>.
|
|
The following articles may be of specific interest:
|
|
<itemizedlist>
|
|
<listitem><para><ulink url="http://www.useit.com/papers/webwriting/">Writing for the Web</ulink></para></listitem>
|
|
<listitem><para><ulink url="http://useit.com/alertbox/20030811.html">Information pollution</ulink></para></listitem>
|
|
<listitem><para><ulink url="http://useit.com/alertbox/9703b.html">Be Succinct! (Writing for the Web)</ulink></para></listitem>
|
|
</itemizedlist>
|
|
There are many, many resources for writing web
|
|
documents--a quick web search for <quote>web
|
|
writing</quote> will find lots of resources.
|
|
Don't get too distracted, though: the ultimate goal is to
|
|
write, not to read about writing!
|
|
</para>
|
|
|
|
<section id="writing-style">
|
|
<!-- Section Added by ejh: August 12, 2003 -->
|
|
<title>Writing Style and Style Guides</title>
|
|
<para>
|
|
There are a number of industry style guides which define how language
|
|
should be used in documents. A common example for American English is
|
|
the <ulink
|
|
url="http://www.chicagomanualofstyle.org/">Chicago Manual
|
|
of Style</ulink>. It defines things like: whether a period (.) should be inside or
|
|
outside of <quote>quotes</quote>; and the format for citing
|
|
another document. A style guide helps to keep documents
|
|
consistent--most corporations will follow a style guide to
|
|
format media releases and other promotional material.
|
|
Style guides mays also define how words should be spelled
|
|
(is it color or colour?).
|
|
</para>
|
|
<para>
|
|
The LDP does not require a specific style
|
|
guide; however, you should use a consistent style throughout your
|
|
document. Your document should be spell checked for a single
|
|
language (e.g. American English vs. British English).
|
|
The <ulink url="http://tldp.org/HOWTO/LDP-Reviewer-HOWTO/">Reviewer's HOWTO</ulink> currently lists a number of
|
|
conventions for LDP documents and it is as close as it
|
|
gets to an official LDP Style Guide.
|
|
</para>
|
|
|
|
<tip><title>A personal glossary</title>
|
|
<para>It helps to make a list of terms that you were new to you when you
|
|
first started researching and writing your document. You can refer to this
|
|
list while writing the text. You may also want to include it as a glossary in
|
|
your final document.
|
|
</para></tip>
|
|
|
|
<para>
|
|
You can save yourself a lot of time in the editing phase if you
|
|
decide how you will write your document ahead of time. If you are
|
|
taking over someone else's document you may need to either: modify
|
|
your own style to fit the current document; or edit the
|
|
document so that it melds with the style you would like to
|
|
use from now on.
|
|
</para>
|
|
|
|
<para>
|
|
From a writing style perspective, use of the
|
|
first-person in a HOWTO adds to its charm--an attribute most
|
|
other documentation sorely lacks. Don't be afraid
|
|
to speak for yourself--use the word <quote>I</quote> to
|
|
describe your personal experiences and opinions.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="writing-resources">
|
|
<title>On-line Writing Resources</title>
|
|
|
|
<para>
|
|
In the <xref linkend="ref-techwriting" />
|
|
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>
|
|
</section> <!-- writing-resources -->
|
|
</section> <!-- sg-writingstyle -->
|
|
|
|
<section id="sg-editing">
|
|
<title>Edit and Proofread 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 <emphasis>[extraneous]</emphasis> material that
|
|
has crept its way into your document.
|
|
You should go through your HOWTO carefully, and ruthlessly
|
|
delete anything that does not 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. Now is the time to correct that. It
|
|
often helps to leave a bit of time between when you write a document
|
|
and when you edit it.
|
|
</para>
|
|
|
|
<para>
|
|
Make sure that the content of every section matches the title
|
|
precisely. It's possible that your original subject heading
|
|
is no longer relevant. If you've strayed from your original heading
|
|
it could mean one of the following: the original title was poorly
|
|
worded, the new material should actually go in a different section,
|
|
or the new material is not really necessary for your document. If you
|
|
need to change a title, check to see if the original subject heading
|
|
is still important. If it is, make sure that topic is covered somewhere
|
|
else in the document.
|
|
</para>
|
|
|
|
<para>
|
|
When editing and proofing your work, check for obvious mistakes,
|
|
such as spelling errors and typos. You should also check for deeper, but
|
|
less obvious errors as well, such as <quote>holes</quote> in the
|
|
information. If you are creating a set of instructions it may
|
|
help to test them on a new machine. Sometimes there
|
|
are packages that need to be installed which you've forgotten to
|
|
mention in your documentation, for instance.
|
|
</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.
|
|
Have others test the instructions as
|
|
well. Make sure they follow exactly what you have written. Ask anyone
|
|
who tests your documentation to make specific notes in any places
|
|
where they didn't follow your instructions (and the reason why they
|
|
didn't follow them). For example: <quote>I skipped step 2 because I
|
|
already have the required packages installed.</quote>
|
|
</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,
|
|
and neither does having a writer edit their own document.
|
|
Recruit a friend, or write the discuss list
|
|
to find a volunteer to proofread before submitting your document. You
|
|
may also want to submit your document to a mailing list that is
|
|
relevant to your document's topic. List members should be able to
|
|
help check the facts, clarity of your instructions and language of
|
|
the document.
|
|
</para>
|
|
|
|
<note><title>Native speaker?</title>
|
|
<para>
|
|
If you are writing in a language in which you are not fluent,
|
|
find an editor who is. Technical
|
|
documentation, more than any other type of writing, must use
|
|
extremely precise grammar and vocabulary. Misuse of language
|
|
makes your document less valuable.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="tools-writing">
|
|
<title>Tools for Writing, Editing and Maintaining your Document</title>
|
|
<caution><title>Reminder</title><para>
|
|
You do <emphasis>not</emphasis> need to submit your
|
|
initial document to the LDP in anything more than plain text! Other open
|
|
submission formats are accepted as well, for instance OpenOffice documents,
|
|
RTF files or HTML. The LDP volunteers will convert your document to DocBook
|
|
for you. Once it has been converted you will need to maintain your document
|
|
in DocBook format, but that should be obvious.
|
|
</para></caution>
|
|
|
|
<section id="ag-edittools">
|
|
<title>Editing Tools</title>
|
|
<para>
|
|
You may use any word processing or text editing tool to write your
|
|
initial document. When you get to the markup stage you may want to use
|
|
a text editor which recognizes DocBook files. At a minimum a program
|
|
which adds syntax highlighting to your markup will make life a lot
|
|
easier. For a description of editors which can handle DocBook files
|
|
please skip to <xref linkend="tools-edit" />.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="git-brief">
|
|
<title>git</title>
|
|
|
|
<para>
|
|
For more information on how to use git to maintain your LDP
|
|
documents, please read <xref linkend="git" />.
|
|
</para>
|
|
</section> <!-- git -->
|
|
|
|
<section id="ag-spellcheck">
|
|
<title>Spell Check</title>
|
|
|
|
<para>
|
|
Some writing tools will come with their own built-in spell
|
|
check tools. This list is only if your application does not
|
|
have a spell check option.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<title>Spell Check Software</title>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<application>aspell</application>
|
|
<ulink url="http://aspell.sourceforge.net" />
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This spell check application can work around XML tags. By
|
|
distinguishing between content and markup aspell is able to check
|
|
your content and ignore the bits it shouldn't be looking at. If you
|
|
are getting spelling errors in your markup tags you may be using an
|
|
old version and should upgrade.
|
|
</para>
|
|
<para>The <command>aspell</command> command comes with the <application>aspell</application> package, included on most Linux distributions. Use the command as follows:</para>
|
|
<cmdsynopsis><command>aspell <option>-c</option> <filename>file</filename></command></cmdsynopsis>
|
|
<para>An interactive user interface allows for fast and easy correction of errors. Use the <option>--help</option> to read more about <command>aspell</command> features.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<application>ispell</application>
|
|
<ulink url="http://www.cs.hmc.edu/~geoff/ispell.html" />
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Similar to <application>aspell</application>, but tries to spell
|
|
check your markup tags. If you have a choice, use
|
|
<application>aspell</application>, if not,
|
|
<application>ispell</application> is a very acceptable substitute.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section> <!-- end of spell check -->
|
|
|
|
|
|
</section> <!-- end writing-tools -->
|
|
</chapter>
|