OWASP Writing Style - Revision history

Paulo Coimbra at 12:15, 20 August 2008

2008-08-20T12:15:05Z

Paulo Coimbra at 16:34, 14 August 2008

2008-08-14T16:34:33Z

Paulo Coimbra at 15:45, 14 August 2008

2008-08-14T15:45:36Z

Pauloc at 20:51, 29 April 2008

2008-04-29T20:51:03Z

Pauloc: /* OWASP Writing style */

2008-04-29T17:45:07Z

‎OWASP Writing style

Pauloc at 17:43, 29 April 2008

2008-04-29T17:43:46Z

Pauloc: /* OWASP Writing style */

2008-04-29T17:27:52Z

‎OWASP Writing style

Pauloc: New page: == OWASP Writing style == 0. 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 [http:/...

2008-04-29T17:05:37Z

New page: == OWASP Writing style == 0. 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 [http:/...

New page

== OWASP Writing style ==

0. 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 [http://en.wikipedia.org/wiki/Plagiarism plagiarism], ensure that the content of articles can be checked by any reader and help users find additional information on the topic. You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite.

; 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 are:

#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’.
#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.

# 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.

# 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.

# 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 then quantity.

# 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.

#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.
# 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.

# 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.

# 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.
Source: Software Documentation, Ian Sommerville, Lancaster University, UK

@@ Line 1: / Line 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 [http://en.wikipedia.org/wiki/Plagiarism plagiarism], ensure that the content of articles can be checked by any reader and help users find additional information on the topic. You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite. Plagiarism is representing another person's work as one's own. According to [http://www.dianahacker.com/ 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 [mailto:owasp@owasp.org owasp@owasp.org] with as many details as possible.
+#'''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 [http://en.wikipedia.org/wiki/Plagiarism plagiarism], ensure that the content of articles can be checked by any reader and help users find additional information on the topic. You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite. Plagiarism is representing another person's work as one's own. According to [http://www.dianahacker.com/ 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. You can use [http://www.articlechecker.com/ this simple tool] to find plagiarism practices. Please report suspected plagiarism to [mailto:owasp@owasp.org owasp@owasp.org] with as many details as possible.
 #'''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’.
 #'''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.

@@ Line 1: / Line 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 [http://en.wikipedia.org/wiki/Plagiarism 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 [http://www.dianahacker.com/ 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 [mailto:owasp@owasp.org owasp@owasp.org] with as many details as possible.You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite. Source: [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources '''Wikipedia'''].
+#'''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 [http://en.wikipedia.org/wiki/Plagiarism plagiarism], ensure that the content of articles can be checked by any reader and help users find additional information on the topic. You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite. Plagiarism is representing another person's work as one's own. According to [http://www.dianahacker.com/ 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 [mailto:owasp@owasp.org owasp@owasp.org] with as many details as possible.
 #'''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’.
 #'''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.

@@ Line 1: / Line 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 [http://en.wikipedia.org/wiki/Plagiarism plagiarism], ensure that the content of articles can be checked by any reader and help users find additional information on the topic. You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite. Source: [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources '''Wikipedia'''].
+#'''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 [http://en.wikipedia.org/wiki/Plagiarism 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 [http://www.dianahacker.com/ 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 [mailto:owasp@owasp.org owasp@owasp.org] with as many details as possible.You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite. Source: [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources '''Wikipedia'''].
 #'''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’.
 #'''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.

@@ Line 4: / Line 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.
 #'''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.
-#'''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 then quantity.
+#'''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.
 #'''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.
 #'''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.

← Older revision		Revision as of 17:45, 29 April 2008
Line 1:		Line 1:
−	~~== OWASP Writing style ==~~
−
	#'''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 [http://en.wikipedia.org/wiki/Plagiarism plagiarism], ensure that the content of articles can be checked by any reader and help users find additional information on the topic. You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite. Source: [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources '''Wikipedia'''].		#'''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 [http://en.wikipedia.org/wiki/Plagiarism plagiarism], ensure that the content of articles can be checked by any reader and help users find additional information on the topic. You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite. Source: [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources '''Wikipedia'''].
	#'''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’.		#'''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’.

@@ Line 1: / Line 1: @@
 == OWASP Writing style ==
-* 0. '''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 [http://en.wikipedia.org/wiki/Plagiarism plagiarism], ensure that the content of articles can be checked by any reader and help users find additional information on the topic. You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite.
+#'''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 [http://en.wikipedia.org/wiki/Plagiarism plagiarism], ensure that the content of articles can be checked by any reader and help users find additional information on the topic. You can see [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources#How_to_cite_sources here] how to cite. Source: [http://en.wikipedia.org/wiki/Wikipedia:Citing_sources '''Wikipedia'''].
-** 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.
+#'''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’.
-** 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 are:
+#'''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.
-* 1. '''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’.
+#'''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.
-* 2. '''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.
+#'''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.
-* 3. '''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.
+#'''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 then quantity.
-* 4. '''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.
+#'''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.
-* 5. '''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 then quantity.
+#'''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.
-* 6. '''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.
+#'''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.
-* 7. '''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.
+#'''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.
-* 8. '''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.
+#'''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, …’.
-* 9. '''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.
+*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.
-* 10. '''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, …’.
+*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.
-** 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.
+*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''': [http://www.literateprogramming.com/documentation.pdf Software Documentation, Ian Sommerville, Lancaster University, UK]