Wednesday, June 07, 2006

Techs writing documentation

I recently read a very good post on Russ Olsen's blog concerning the quality of technical documentation and what people should do to improve their own writing.

I liked it very much, there is deep truth in it. It might seem obvious, but once you really think about yourself in the role of a writer you will see many aspects apply to you. There is one aspect however that I would like to add, because I see it a lot where I work (which happens to be in Germany).

Write in the language of your readers, if you are able to do so, and only then!

We are a German company developing custom software in Java. People have understood that code documentation, Javadoc in this case, is something that can really make your life a lot easier. Unfortunately some people tend to think that each and every source code comment need be in English. This is of course total nonsense, because there is no point in it when all your colleagues are Germans like yourself and it is a closed source application.

The result of this is a lot of comments in clumsy English. A native English speaker would most certainly have a hard time understanding them, because they are often merely word-by-word translations of German sentences. Very often people without experience in English will also use the very popular "false friends".

Therefore I would really like people to think about the language to use, even before they start with the very first word of any documentation.

No comments: