Difference between revisions of "ABC Approach"
(→Organizing Sections and Paragraphs) |
m (→Document Conclusion: capitalization) |
||
| (23 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | {{ | + | {{3040TopicNoBar|Chapter_TOC=[[Common Components]]}} |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
== ABC Format for Documents== | == ABC Format for Documents== | ||
| − | Technical documents should assume three part structure that consists of beginning, middle and end. Every document should begin with an '''Abstract''' or an '''Overview''' that offers a summary of main points. The '''Body''' is the main content section of the document that elaborates on the main topics. The purpose of the '''Conclusion''' is to restate the central points that were covered in the document. | + | Technical documents should assume a three part structure that consists of a beginning, middle and end. Every document should begin with an '''Abstract''' or an '''Overview''' that offers a summary of the main points. The '''Body''' is the main content section of the document that elaborates on the main topics. The purpose of the '''Conclusion''' is to restate the central points that were covered in the document. |
===Document Abstract=== | ===Document Abstract=== | ||
| − | The purpose of | + | The purpose of an abstract is to provide decision makers with the document's highlights. It explains to the readers how a particular document concerns them. An abstract always includes a general conclusion or executive summary, a clear purpose statement, and the most important points for the decision makers. The title and size of this section could vary depending on the purpose and the audience. Document highlights must be brief and yet unambiguous. |
===Document Body=== | ===Document Body=== | ||
| − | The middle section of the document is the body. The purpose of this section is to provide supporting details for the concepts mentioned in the abstract highlights. It is a good idea to write expansively and elaborate on project's background, related work or experience and applicable conclusions and recommendations. Although there are no standard sections that must go into the body, the content | + | The middle section of the document is the body. The purpose of this section is to provide supporting details for the concepts mentioned in the abstract's highlights. It is a good idea to write expansively and elaborate on a project's background, related work or experience, and applicable conclusions and recommendations. Although there are no standard sections that must go into the body, the content should always be in reference to the key points that were introduced in abstract and mentioned in the conclusion. |
| − | The following are suggested guidelines for for writing '''document body''': | + | The following are suggested guidelines for for writing a '''document body''': |
| − | + | *Separate facts from opinions and clearly indicate when you are stating an opinion. | |
| − | + | : Opinions that are derived from technical data should be mentioned as suggestions in the conclusion section of the document. This especially applies when readers have technical backgrounds and will rely on your document to perform their jobs. | |
| − | + | ||
| − | + | ||
| − | + | *Documents should follow a standard structure. Use section headings and frequent subheadings so the reader can find information immediately. | |
| − | + | ||
| − | + | *Introduce graphics to possibly eliminate the reading overhead and to draw attention to important points. This will visually reinforce important details. | |
| − | + | ||
| − | The body should not include raw data in order to preserve the overall flow of information. The body section is there to show | + | The body should not include raw data, in order to preserve the overall flow of information. The body section is there to show supportive information for the key points from the abstract, and not for the reader to derive new concepts. |
===Document Conclusion=== | ===Document Conclusion=== | ||
| − | The final section of the document is the | + | The final section of the document is the conclusion. It will provide a summary of the document's key points to the reader. A good conclusion will effectively describe each main point from the document, so that a reader can have a solid idea about the document's contents. There may also be some direction for future actions by the reader. |
Conclusions can be of the following two formats: | Conclusions can be of the following two formats: | ||
| − | + | *'''Listing''' format is especially useful for displaying the key concepts mentioned throughout the document. | |
| − | + | *'''Summary''' format is appropriate if you cannot make a list of mentioned topics; for example, when a single decision was derived from technical data. | |
| − | + | ||
| − | Both alternatives are suitable for bringing the readers back to the main points to | + | Both alternatives are suitable for bringing the readers back to the main points to aid the decision making process. |
| − | + | ||
| − | + | ||
== Organizing Paragraphs == | == Organizing Paragraphs == | ||
| − | |||
| − | + | As shown above, the ABC format is used for the overall document structure. Similarly, each document construct or paragraph should be designed to contain a beginning, middle and end subsection. This allows readers to easily transition between sections, and will help introduce and reinforce what each paragraph is about. | |
Paragraphs are the basic building block of technical and non-technical documents. '''ABC format''' requires each paragraph to have the following sections: | Paragraphs are the basic building block of technical and non-technical documents. '''ABC format''' requires each paragraph to have the following sections: | ||
| − | + | *Topic sentence - an introductory or a section entry sentence that states the key concepts in a particular paragraph. | |
| − | + | *Main idea development - a subsection that conveys facts about the idea stated above. | |
| − | + | *Transitional elements - parts of sentences that enhance the flow of the paragraph. | |
| − | + | *Closing sentence - either a conclusion about the main point in the paragraph, or a transition into the following paragraph. | |
| + | |||
| + | In some situations the ABC format may not be acceptable for paragraphs; for example, if the paragraph is too short, or requires a brief discussion at the beginning to elaborate on the main point. In these cases and others, alternative paragraph design guidelines should be considered. | ||
| + | |||
| + | Some other guidelines to follow: | ||
| + | * Paragraph size should be kept between 6 and 10 lines. | ||
| + | * To avoid hiding information in long paragraphs, make use of listings. | ||
| + | * Use figures or tables to represent numbers. | ||
| + | |||
| + | ==Further Readings== | ||
| + | Boogerd, Jan, Pfeiffer, William Sanborn, Technical Communication - A Practical Approach, Pearson Education Canada, Toronto, 2007. | ||
| + | |||
| + | http://ewh.ieee.org/soc/pcs/?q=node/24 IEEE Transactions on Professional Communication. | ||
| + | |||
| + | http://en.wikiversity.org/wiki/Technical_writing Wikiversity Technical Writing course | ||
| + | |||
| + | ==References== | ||
| + | Boogerd, Jan, Pfeiffer, William Sanborn, Technical Communication - A Practical Approach, Pearson Education Canada, Toronto, 2007. | ||
| + | |||
| + | http://www.techwr-l.com/techwhirl/index.php3 The internet forum on technical communication. | ||
| − | + | http://en.wikipedia.org/wiki/Technical_communication An official wiki summary page on technical communication. | |
Latest revision as of 03:28, 20 April 2008
Introduction
ABC Format for Documents
Technical documents should assume a three part structure that consists of a beginning, middle and end. Every document should begin with an Abstract or an Overview that offers a summary of the main points. The Body is the main content section of the document that elaborates on the main topics. The purpose of the Conclusion is to restate the central points that were covered in the document.
Document Abstract
The purpose of an abstract is to provide decision makers with the document's highlights. It explains to the readers how a particular document concerns them. An abstract always includes a general conclusion or executive summary, a clear purpose statement, and the most important points for the decision makers. The title and size of this section could vary depending on the purpose and the audience. Document highlights must be brief and yet unambiguous.
Document Body
The middle section of the document is the body. The purpose of this section is to provide supporting details for the concepts mentioned in the abstract's highlights. It is a good idea to write expansively and elaborate on a project's background, related work or experience, and applicable conclusions and recommendations. Although there are no standard sections that must go into the body, the content should always be in reference to the key points that were introduced in abstract and mentioned in the conclusion.
The following are suggested guidelines for for writing a document body:
- Separate facts from opinions and clearly indicate when you are stating an opinion.
- Opinions that are derived from technical data should be mentioned as suggestions in the conclusion section of the document. This especially applies when readers have technical backgrounds and will rely on your document to perform their jobs.
- Documents should follow a standard structure. Use section headings and frequent subheadings so the reader can find information immediately.
- Introduce graphics to possibly eliminate the reading overhead and to draw attention to important points. This will visually reinforce important details.
The body should not include raw data, in order to preserve the overall flow of information. The body section is there to show supportive information for the key points from the abstract, and not for the reader to derive new concepts.
Document Conclusion
The final section of the document is the conclusion. It will provide a summary of the document's key points to the reader. A good conclusion will effectively describe each main point from the document, so that a reader can have a solid idea about the document's contents. There may also be some direction for future actions by the reader.
Conclusions can be of the following two formats:
- Listing format is especially useful for displaying the key concepts mentioned throughout the document.
- Summary format is appropriate if you cannot make a list of mentioned topics; for example, when a single decision was derived from technical data.
Both alternatives are suitable for bringing the readers back to the main points to aid the decision making process.
Organizing Paragraphs
As shown above, the ABC format is used for the overall document structure. Similarly, each document construct or paragraph should be designed to contain a beginning, middle and end subsection. This allows readers to easily transition between sections, and will help introduce and reinforce what each paragraph is about.
Paragraphs are the basic building block of technical and non-technical documents. ABC format requires each paragraph to have the following sections:
- Topic sentence - an introductory or a section entry sentence that states the key concepts in a particular paragraph.
- Main idea development - a subsection that conveys facts about the idea stated above.
- Transitional elements - parts of sentences that enhance the flow of the paragraph.
- Closing sentence - either a conclusion about the main point in the paragraph, or a transition into the following paragraph.
In some situations the ABC format may not be acceptable for paragraphs; for example, if the paragraph is too short, or requires a brief discussion at the beginning to elaborate on the main point. In these cases and others, alternative paragraph design guidelines should be considered.
Some other guidelines to follow:
- Paragraph size should be kept between 6 and 10 lines.
- To avoid hiding information in long paragraphs, make use of listings.
- Use figures or tables to represent numbers.
Further Readings
Boogerd, Jan, Pfeiffer, William Sanborn, Technical Communication - A Practical Approach, Pearson Education Canada, Toronto, 2007.
http://ewh.ieee.org/soc/pcs/?q=node/24 IEEE Transactions on Professional Communication.
http://en.wikiversity.org/wiki/Technical_writing Wikiversity Technical Writing course
References
Boogerd, Jan, Pfeiffer, William Sanborn, Technical Communication - A Practical Approach, Pearson Education Canada, Toronto, 2007.
http://www.techwr-l.com/techwhirl/index.php3 The internet forum on technical communication.
http://en.wikipedia.org/wiki/Technical_communication An official wiki summary page on technical communication.
