| Firebird Documentation Index → Firebird Docwriting Guide → Language and style |
|
|
|
After the flood of DocBook information in the previous sections, we now turn our attention to some other important docwriting aspects: language and style (in this section), and copyrights (in the next section).
The Firebird community is a very diverse one, and made up of people with many different mother tongues. If you write your documentation in a language other than your own, you'll probably make some mistakes. This is not catastrophical, but you should at least try to reduce the number of errors. Some strategies to help you with this are:
Use a dictionary! Simple, effective, and blissfully non-hightech.
When hesitating between two spellings of a word, or between several possible versions of an expression, google for the alternatives and look at their frequencies. Also follow some of the result links to see how native speakers use the word or expression in their texts.
Have a native speaker look over your text and correct it where necessary.
Don't expect a Style Guide here – I wouldn't know how to write one anyway. Just some guidelines and tips:
Try to write in plain, everyday language wherever possible. Avoid difficult words if there's a familiar, simple alternative.
Avoid long sentences (over 25 words) if you can; especially avoid two or more long sentences immediately after each other.
Be careful with constructs like double or triple negatives (“I can't deny that I'm not displeased”) and passive voice (“Care should be taken...”). You don't have to avoid them at all costs, but they can make a sentence harder to understand. To prevent that, use the positive (“I am pleased”) and the active voice (“Take care...”).
Use lists to enumerate a number of parallel items, for instance:
A collection of hints and tips.
A sequence of examples (like this one).
Steps to be followed in a procedure.
Alternative solutions to a problem.
But if there's only a small number of short items, use a plain sentence instead: “My mother loves three men: John, Dick, and Dave.”
Don't overuse exclamation marks. Never use multiple exclamation marks or question marks. This is annoying!!!!! Don't you agree???
Sometimes you know what you want to write, and you have all the words ready, but you can't get the sentence started – you just don't get it to flow. This is very frustrating and it can sometimes block the advance of your text for many minutes. And it's all the more frustrating because you do know what you want to tell your readers, but you don't seem to be able to produce a decent sentence. After many painful experiences of this kind, I've developed the following strategy (not that I think I'm the first):
Write down what you have to say in loose sentences and chunks of words. Never mind about style, never mind if it looks ugly. Just write down what you want to tell the reader; make sure it's all there, and in the right order. If, while doing this, you notice that you feel unsure about something, include a remark at exactly that point. Make your remarks stand out from the surrounding text, e.g. <<like this>> or !LIKE THAT!
This may result in a text like:
git is a distributed version-control system (<<check!>>). Purpose: managing versions of source code. You can use it alone or with a group. You need a git client to use it. A git client is a program with which you can access a git repository (<<explain this term?>>). To find out if a git client is installed on your system, type “git” on the command line. If it's not there, go to this URL to download it.... [etc., etc.]
If you have included any remarks, handle them first. Check if git really is a distributed version-control system (it is). Decide whether you should really explain the term “git repository” at this point (you should).
Now, go over the paragraph again and try to make the text flow more naturally wherever you can. Chances are that this will be a lot easier than you expected!
If it still looks a little clumsy, never mind – better clumsy and clear than smooth-flowing and fuzzy. Maybe you can revisit this passage later and see if you can nice it up some more.
This approach works well for me. So if you're stuck in this way, try it out; hopefully it will help you too.
|
| Firebird Documentation Index → Firebird Docwriting Guide → Language and style |