mirror of https://github.com/tLDP/LDP
280 lines
11 KiB
XML
280 lines
11 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>
|
|
Hopefully by 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. If you're
|
|
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 dry,
|
|
boring information in your own unique way.
|
|
</para>
|
|
|
|
<!--
|
|
Removed the Politics and the English Language section. It was not
|
|
gender-neutral and therefore potentially offensive to female
|
|
authors. Well it was at least off-putting to THIS female
|
|
author.
|
|
I have linked to the full text in the resources section.
|
|
-->
|
|
|
|
<para>
|
|
If it hasn't become painfully obvious yet all of these
|
|
suggestions are about keeping your documents simple.
|
|
Your readers are already struggling with new concepts, so don't
|
|
make them struggle to understand your language.
|
|
</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 the resources section. 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:
|
|
<ulink url="http://www.useit.com/papers/webwriting/">Writing for the
|
|
Web</ulink>,
|
|
<ulink url="http://useit.com/alertbox/20030811.html">Information
|
|
pollution</ulink>, and
|
|
<ulink url="http://useit.com/alertbox/9703b.html">Be Succinct!
|
|
(Writing for the Web)</ulink>.
|
|
There are many, many resources for writing web
|
|
documents--a quick web search for <quote>web
|
|
writing</quote> will find lots of resources. (But
|
|
don't get too distracted--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 a 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 is as close as it
|
|
gets to an official LDP Style Guide.
|
|
</para>
|
|
|
|
<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>.
|
|
Describe your personal experiences and opinions.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="writing-resources">
|
|
<title>Online Writing Resources</title>
|
|
|
|
<para>
|
|
In the <xref linkend="references-techwriting" endterm="references-techwriting.title" />
|
|
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 [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. 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 contents of every section match the title of that
|
|
section 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 fresh machine. Sometimes there
|
|
are packages that need to be installed which you've forgotten to
|
|
mention in your documentation.
|
|
</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>
|
|
<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 HOWTO less valuable.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="tools-writing">
|
|
<title>Writing Tools (for the slightly more courageous)</title>
|
|
<caution><para>
|
|
As a reminder: you do <emphasis>not</emphasis> need to submit your
|
|
initial document to the LDP in anything more than plain text! 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.
|
|
</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="cvs-brief">
|
|
<title>Concurrent Versions System (CVS)</title>
|
|
&cvs-why;
|
|
|
|
<para>
|
|
For more information on how to use CVS to maintain your LDP
|
|
documents, please read <xref linkend="cvs" />.
|
|
</para>
|
|
</section> <!-- cvs -->
|
|
|
|
|
|
<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>
|
|
|
|
<section id="aspell">
|
|
<title>aspell</title>
|
|
<para><ulink
|
|
url="http://aspell.sourceforge.net/">http://aspell.sourceforge.net/</ulink></para>
|
|
<para>This spell checking 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>
|
|
Some may prefer to use <application>ispell</application>.
|
|
It is available from
|
|
<ulink url="http://www.cs.hmc.edu/~geoff/ispell.html">http://www.cs.hmc.edu/~geoff/ispell.html</ulink>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
</section> <!-- end writing-tools -->
|
|
</chapter>
|