writing
Writing
1. Why does writing matter?
The documentation is already easy to understand. But we can always try and do even better. Let's share ideas for improving the documentation here.
These are not rules. You don't have to follow these suggestions (or even read them) to contribute to the [[documentation]].
2. Writing
2.1 Use headings
Headings let the reader know what a paragraph (or set of paragraphs) are about. Headings let the reader skim and skip what she doesn't need.
2.2 Subject-verb-object
Keep the subject, verb, and object close together in the sentence.
(define each)
2.3 Active voice > passive voice
A passive sentence might read “Updates to your system should be done now.” The same sentence in the active voice would read “You should update your system now.” The active sentence says who is responsible for the action.
Most of the time, the reader will figure out what the writer means from context. But sometimes, passive sentence structure can make instructions tricky to follow.
Passive sentences can also sound impersonal.
2.4 Topic paragraphs
The first sentence of your paragraph should indicate what the rest of your paragraph is about. The first sentence is the conclusion. The sentences that follow support (detail) the first sentence. For example:
“Next you'll install *Diaspora on your Trisquel server. You may do this from the terminal, or with Add/Remove Programs. The terminal is the easier, but some people prefer Add/Remove Programs because abc”
Start a new paragraph when you move on to a new idea or topic. This way, a reader can skim the first sentences of paragraphs within a heading, to find what she's looking for.
2.5 Topic sentence
The beginning of your sentence should tell the reader what the rest of the sentence is about. The preceeding sentence was about the beginning part of a sentence, so it started out with “The beginning of your sentence[...].”
3. Organization
3.1 If we talk about many similar applications, or offer the user many ways of doing a task, consider presenting them as a list.
For example, insted of:
You could use email app1, email app2, email app3, email app 4, email app 5, email app6, or email app7.
Try:
(a) email app1
(b) email app2
(c) email app3
etc.
