Technical Writing-Best Practices
Submitted by Alka on Mon, 06/09/2008 - 07:00
Printer-friendly version
Printer-friendly versionHere are some of the best practices useful in technical writing:
Analyze the audience.
The audience is "the most important consideration in planning, writing, and reviewing a document."1 To write effective documentation that suits the users, we must understand their needs. In other words, ProEdit doesn't create a 300-page manual when a quick reference guide will do.
Write reader-friendly documentation.
Technical writing is full of complex information. ProEdit writes documentation to your audience's readability level. Many methods exist to test readability, including the Gunning's Fog Index and the SMOG Index. Microsoft Word also includes a Flesch-Kincaid readability tool to check the readability of a document.
Use active voice.
It is commonly held that passive voice is acceptable in scientific and technical writing. However, overuse of passive voice, or use of passive voice in long and complicated sentences, can cause readers to lose interest or to become confused.2 ProEdit uses active voice to ensure that your readers and users clearly understand your documentation.
Use advance organizers.
In technical writing, an advance organizer (also called a "jump list") is a bulleted list at the beginning of a chapter that provides an overview of the chapter. "The most important single factor influencing learning is what the learner already knows."3 Advance organizers help users process and retain information based on what they already know.
More coming soon........................
Bookmark/Search this post with
»
Readability
I did not know that even readability could be tested. Its interesting to know that there are tools to test readability. I was under this impression that if a document is written in a lucid manner, it will improve readability, and that it is an effective way of ensuring that the document can be read by many people.
Would you care to elaborate more on the Gunning's Fog and SMOG Index? And, where is Flesch-Kincaid readability tool in MS Word, is it a plugin?
-Madhuri
Readibility Testing!!
Readability tests, readability formulas, or readability metrics are formulae for evaluating the readability of text, usually by counting syllables, words, and sentences. Readability tests are often used as an alternative to conducting an actual statistical survey of human readers of the subject text (a readability survey). Word processing applications often have readability tests in-built, which can be deployed on documents in-editing.
The application of a useful readability test protocol will give a rough indication of a work's readability, with accuracy increasing when finding the average readability of a large number of works. The tests generate a score based on characteristics such as statistical average word length (which is a used as a proxy for semantic difficulty) and sentence length (as a proxy for syntactic complexity) of the work.
Some readability formulas refer to a list of words graded for difficulty. These formulas attempt to overcome the fact that some words, like "television", are well known to younger children, but have many syllables. In practice, however, the utility of simple word and sentence length measures make them more popular for readability formulas.[citation needed] Scores are compared with scales based on judged linguistic difficulty or reading grade level. Many readability formulas measure word length in syllables rather than letters, but only SMOG has a computerized readability program incorporating an accurate syllable counter.
Since readability formulas do not take the meanings of words into account, they are not considered definitive measures of readability.
SMOG (Simple Measure of Gobbledygook) is a readability formula that estimates the years of education needed to completely understand a piece of writing. SMOG is widely used, particularly for checking health messages [1]. The precise SMOG formula yields an outstandingly high 0.985 correlation with the grades of readers who had 100% comprehension of test materials.[citation needed]
SMOG was published by G. Harry McLaughlin in 1969[2] as a more accurate and more easily calculated substitute for the Gunning-Fog Index. To make calculating a text’s readability as simple as possible an approximate formula was also given — count the words of 3 or more syllables in 3 10-sentence samples, estimate the count’s square root (from the nearest perfect square), and add 3.
[edit] Formula
To calculate SMOG
1. Count a number of sentences (at least: 10 from the start of a text, 10 from the middle, and 10 from the end).
2. In those sentences count the polysyllables (words of 3 or more syllables).
3. Apply this formula:
Here is the link to free SMOG Calculator!!
http://www.harrymclaughlin.com/SMOG.htm