mirror of https://github.com/tLDP/LDP
258 lines
11 KiB
XML
258 lines
11 KiB
XML
<chapter id="write">
|
|
<title>Write</title>
|
|
|
|
<setion 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 off-putting to female authors.
|
|
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 online. 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
|
|
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 specifically
|
|
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</a>.
|
|
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. If you're
|
|
feeling inclined a web search will turn up lots of resources. (But
|
|
don't get too distracted--the ultimate goal is to write your document, not
|
|
spend your time reading 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 use a style guide to format media
|
|
releases and other promotional material. It may also define how words
|
|
should be spelled (is it color or colour?). The LDP does not require
|
|
you to use 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).
|
|
</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 purely stylistic point of view 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>
|
|
</section>
|
|
|
|
<section id="writing-resources">
|
|
<title>Online Writing Resources</title>
|
|
|
|
<para>
|
|
In the <quote><link linkend="references-techwriting"
|
|
endterm="references-techwriting.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>
|
|
</section> <!-- writing-resources -->
|
|
</setion> <!-- sg-writingstyle -->
|
|
|
|
<setion 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 relevent. 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
|
|
relevent 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">
|
|
<title>Writing Tools (for the slightly more courageous)</title>
|
|
<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.
|
|
The next chapter, Markup, will help you with the maintenance of your
|
|
document.
|
|
FIXME: add a link to the next chapter
|
|
</para>
|
|
|
|
<section id="tools-editors">
|
|
<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 Editors, Validation and System Setup.
|
|
FIXME: add a link to the appendix
|
|
</para>
|
|
</section>
|
|
|
|
<!--
|
|
I really am trying to hack the CVS section down and either remove it
|
|
completely or at least move it to an appendix. too tired right now so
|
|
the entity reference remains:
|
|
-->
|
|
&cvs;
|
|
|
|
<section id="tools-other">
|
|
<title>Spell Check</title>
|
|
<section id="aspell">
|
|
<title>Aspell</title>
|
|
<para>Optional - <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>
|
|
</section>
|
|
<section id="ispell">
|
|
<title>ispell</title>
|
|
<para>Optional - <ulink url="http://www.cs.hmc.edu/~geoff/ispell.html">http://www.cs.hmc.edu/~geoff/ispell.html</ulink></para>
|
|
<para>The ispell program is distributed with RedHat (and possibly other
|
|
distros) and also ignores markup tags.</para>
|
|
</section>
|
|
</section>
|
|
|
|
</section> <!-- end writing-tools -->
|
|
</chapter>
|