Difference between revisions of "OWASP Writing Style"

Revision as of 15:45, 14 August 2008

1. Cite your sources. The reader needs to be assured that the material within it is reliable. This will improve the credibility of OWASP, avoid claims of plagiarism, ensure that the content of articles can be checked by any reader and help users find additional information on the topic. Plagiarism is representing another person's work as one's own. According to Diana Hacker, "Three acts are plagiarism: (1) failing to cite quotations and borrowed ideas, (2) failing to enclose borrowed language in quotation marks and (3) failing to put summaries and paraphrases in your own words." Plagiarism is inconsistent with OWASP's goals and will result in permanent removal of your material from our site. Please report suspected plagiarism to [email protected] with as many details as possible.You can see here how to cite. Source: Wikipedia.
2. Use active rather than passive tenses. It is better to say ‘You should see a flashing cursor at the top left of the screen’ rather than ‘A flashing cursor should appear at the top left of the screen’.
3. Use grammatically correct constructs and correct spelling. To boldly go on splitting infinitives (like this) and to misspell words (like mispell) irritates many readers and reduces the credibility of the writer in their eyes. Unfortunately, English spelling is not standardized and both British and American readers are sometimes irrational in their dislike of alternative spellings.
4. Do not use long sentences which present several different facts. It is better to use a number of shorter sentences. Each sentence can then be assimilated on its own. The reader does not need to maintain several pieces of information at one time to understand the complete sentence.
5. Keep paragraphs short. As a general rule, no paragraph should be made up of more than seven sentences. Our capacity for holding immediate information is limited. In short paragraphs, all of the concepts in the paragraph can be maintained in our short-term memory which can hold about 7 chunks of information.
6. Don’t be verbose. If you can say something in a few words do so. A lengthy description is not necessarily more profound. Quality is more important than quantity.
7. Be precise and define the terms which you use. Computing terminology is fluid and many terms have more than one meaning. If you use terms like module or process make sure that your definition is clear. Collect definitions in a glossary.
8. If a description is complex, repeat yourself. It is often a good idea to present two or more differently phrased descriptions of the same thing. If readers fail to completely understand one description, they may benefit from having the same thing said in a different way.
9. Make use of headings and sub-headings. These break up a chapter into parts which may be read separately. Always ensure that a consistent numbering convention is used.
10. Itemize facts wherever possible. It is usually clearer to present facts in a list rather than in a sentence. Use textual highlighting (italics or underlining) for emphasis.
11. Do not refer to information by reference number alone. Give the reference number and remind the reader what that reference covered. For example, rather than say ‘In section 1.3 …’ you should say ‘In section 1.3, which described management process models, …’.

• Documents should be inspected in the same way as programs. During a document inspection, the text is criticized, omissions pointed out and suggestions made on how to improve the document. In this latter respect, it differs from a code inspection which is an error finding rather than an error correction mechanism. As well as personal criticism, you can also use grammar checkers which are incorporated in word processors. These checkers find ungrammatical or clumsy uses of words. They identify long sentences and paragraphs and the use of passive rather than active tenses. These checkers are not perfect and sometimes they use outmoded style rules or rules which are specific to one country. Nevertheless, because they often check style as you are typing, they can help identify phrases which could be improved.
• Standards and quality assessment are essential if good documentation is to be produced but document quality is fundamentally dependent on the writer’s ability to construct clear and concise technical prose. In short, good documentation requires good writing.
• Writing documents well is neither easy nor is it a single stage process. Written work must be written, read, criticized and then rewritten until a satisfactory document is produced. Technical writing is a craft rather than a science but some broad guide-lines about how to write well can be found above.

Source: Software Documentation, Ian Sommerville, Lancaster University, UK.