Message-ID: <75393599.1584.1556111943731.JavaMail.javamailuser@localhost>
Subject: Exported From Confluence
MIME-Version: 1.0
Content-Type: multipart/related;
boundary="----=_Part_1583_1571358915.1556111943730"
------=_Part_1583_1571358915.1556111943730
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Content-Location: file:///C:/exported.html
General writing guidelines
General writing guidelines
Follow these guidelines to ensure your documentation is clear, c=
omprehensible and easy to translate:
Grammar and Usage
=09- write with the reader in mind
=09- write self-descriptive topic headings that clearly identify the topi=
c
=09- use short, simple sentences and words
=09- start with the most important idea
=09- be consistent in terminology and spelling: do not call the same thin=
g by different names, and do not call more than one thing by the same name<=
/li>
=09
- use active voice: for example: Use the Save command to save the =
file, not The Save command is used to save the file.
=09- use graphics and diagrams where possible
=09- avoid text in graphics
=09- avoid double-negatives
=09- avoid acronyms, but if you must use them, expand the acronym on its =
first use
=09- avoid idioms, colloquialisms, and slang
=09- write each sentence in chronological order
=09- avoid contractions
=09- have one idea per sentence
=09- have one topic per paragraph
=09- start the paragraph with a topic (introductory) sentence
=09- use proper grammar
=09- avoid starting a sentence with a conjunction
=09- avoid sentence fragments
=09- be sensitive to other cultures and countries
=09- avoid gender-specific language (he, she)
=09- avoid abstract nouns, for example, using capability to indi=
cate you can
=09- consider generic placement of graphics
=09- write with accessibility in mind: use tooltips on graphics, font siz=
e, alternate text
=09- avoid deadwood words: for example: Pick a valid code should be P=
ick a code
=09- do not write as if things were people, for example, The computer=
remembers.
=09- avoid long adjective strings - use prepositions between str=
ings
=09- if possible, identify which country the topic applies to
Documentation structure
=09- start with a summary paragraph
=09- avoid long text blocks
=09- use bullets, lists, tables and numbering where appropriate
=09- avoid long paragraphs and sentences
=09- use headings and white space
=09- use a glossary to define each terms
------=_Part_1583_1571358915.1556111943730--