347 lines
7.1 KiB
HTML
347 lines
7.1 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Writing the Text</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
|
|
REL="HOME"
|
|
TITLE="LDP Author Guide"
|
|
HREF="index.html"><LINK
|
|
REL="UP"
|
|
TITLE="Write"
|
|
HREF="write.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Write"
|
|
HREF="write.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="Edit and Proofread the Text"
|
|
HREF="sg-editing.html"></HEAD
|
|
><BODY
|
|
CLASS="section"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>LDP Author Guide</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="write.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
>Chapter 4. Write</TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="sg-editing.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H1
|
|
CLASS="section"
|
|
><A
|
|
NAME="sg-writingstyle"
|
|
></A
|
|
>4.1. Writing the Text</H1
|
|
><P
|
|
> 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.
|
|
</P
|
|
><P
|
|
> 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.
|
|
</P
|
|
><P
|
|
> 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 . Also listed in the
|
|
resources section are a variety of sites that have
|
|
information specific to technical writing.
|
|
</P
|
|
><P
|
|
> The Author Guide wouldn't be complete without
|
|
mentioning the Plain Language movement. Although
|
|
directed at simplifying government documents, <A
|
|
HREF="http://www.blm.gov/nhp/NPR/pe_toc.html"
|
|
TARGET="_top"
|
|
>Writing user-friendly
|
|
documents</A
|
|
> is quite useful. It includes before and after
|
|
writing samples. There's also a
|
|
<A
|
|
HREF="http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html"
|
|
TARGET="_top"
|
|
>PlainTrain
|
|
writing tutorial</A
|
|
>.
|
|
</P
|
|
><P
|
|
> And any document that discusses writing for the web wouldn't be complete without
|
|
a nod toward <A
|
|
HREF="http://www.useit.com"
|
|
TARGET="_top"
|
|
>useit.com</A
|
|
>.
|
|
The following articles may be of specific interest:
|
|
<P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
><A
|
|
HREF="http://www.useit.com/papers/webwriting/"
|
|
TARGET="_top"
|
|
>Writing for the Web</A
|
|
></P
|
|
></LI
|
|
><LI
|
|
><P
|
|
><A
|
|
HREF="http://useit.com/alertbox/20030811.html"
|
|
TARGET="_top"
|
|
>Information pollution</A
|
|
></P
|
|
></LI
|
|
><LI
|
|
><P
|
|
><A
|
|
HREF="http://useit.com/alertbox/9703b.html"
|
|
TARGET="_top"
|
|
>Be Succinct! (Writing for the Web)</A
|
|
></P
|
|
></LI
|
|
></UL
|
|
>
|
|
There are many, many resources for writing web
|
|
documents--a quick web search for <SPAN
|
|
CLASS="QUOTE"
|
|
>"web
|
|
writing"</SPAN
|
|
> will find lots of resources.
|
|
Don't get too distracted, though: the ultimate goal is to
|
|
write, not to read about writing!
|
|
</P
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="writing-style"
|
|
></A
|
|
>4.1.1. Writing Style and Style Guides</H2
|
|
><P
|
|
> 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 <A
|
|
HREF="http://www.chicagomanualofstyle.org/"
|
|
TARGET="_top"
|
|
>Chicago Manual
|
|
of Style</A
|
|
>. It defines things like: whether a period (.) should be inside or
|
|
outside of <SPAN
|
|
CLASS="QUOTE"
|
|
>"quotes"</SPAN
|
|
>; 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?).
|
|
</P
|
|
><P
|
|
> 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 <A
|
|
HREF="http://tldp.org/HOWTO/LDP-Reviewer-HOWTO/"
|
|
TARGET="_top"
|
|
>Reviewer's HOWTO</A
|
|
> currently lists a number of
|
|
conventions for LDP documents and it is as close as it
|
|
gets to an official LDP Style Guide.
|
|
</P
|
|
><DIV
|
|
CLASS="tip"
|
|
><P
|
|
></P
|
|
><TABLE
|
|
CLASS="tip"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="25"
|
|
ALIGN="CENTER"
|
|
VALIGN="TOP"
|
|
><IMG
|
|
SRC="../images/tip.gif"
|
|
HSPACE="5"
|
|
ALT="Tip"></TD
|
|
><TH
|
|
ALIGN="LEFT"
|
|
VALIGN="CENTER"
|
|
><B
|
|
>A personal glossary</B
|
|
></TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
> </TD
|
|
><TD
|
|
ALIGN="LEFT"
|
|
VALIGN="TOP"
|
|
><P
|
|
>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.
|
|
</P
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><P
|
|
> 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.
|
|
</P
|
|
><P
|
|
> 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 <SPAN
|
|
CLASS="QUOTE"
|
|
>"I"</SPAN
|
|
> to
|
|
describe your personal experiences and opinions.
|
|
</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="section"
|
|
><H2
|
|
CLASS="section"
|
|
><A
|
|
NAME="writing-resources"
|
|
></A
|
|
>4.1.2. On-line Writing Resources</H2
|
|
><P
|
|
> In the
|
|
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.
|
|
</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="write.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="sg-editing.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Write</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="write.html"
|
|
ACCESSKEY="U"
|
|
>Up</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>Edit and Proofread the Text</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |