Help:Effective technical writing: Difference between revisions
Jump to navigation
Jump to search
Content added Content deleted
imported>Rob Kam No edit summary |
imported>Rob Kam m (removed Category:Help:Editing; added Category:Help using HotCat) |
||
Line 64: | Line 64: | ||
* [https://archive.org/search.php?query=heathkit%20manual Heathkit manuals], Archive.org |
* [https://archive.org/search.php?query=heathkit%20manual Heathkit manuals], Archive.org |
||
[[Category:Help |
[[Category:Help]] |
||
[[Category:Meta]] |
[[Category:Meta]] |
Revision as of 21:12, 27 January 2020
This attempts to outline some basic principles for effective technical writing. How to communicate practical knowledge about a complex subject and break it down into understandable chunks.[1]
Key features
Collaborate
- Technical documents are hardly ever written alone.
- Ask the experts.
Clear communication
- Don't write an essay.
- Images and illustrations can explain better than words.
- Put yourself in the reader's place; write appropriately for your intended audience.
- Use real world examples that your audience will understand.
- Use plain readily understood words.
- Use words with unambiguous meanings.
- Be concise, cut out redundant words.
- Use precise terminology.
- Avoid jargon.
- Avoid acronyms.
- Don't use allusions. Your audience might not know to what you're referring.
- Use short sentences 15 to 25 words on average.
- One sentence per idea.
- Break the text up, one concept per paragraph.
- Use plenty of white space in between the sentences.
- Use the active voice.
- Do not use adverbs.[2]
- Do not use adjectives.[2][3]
- Avoid making nouns from verbs.
- Use good grammar and punctuation. Use a spellchecker before saving.
- Review what you've written, to catch any errors you may have made.
- Try to balance comprehensive coverage with not overwhelming with too much information.
- Use a consistent familiar style.
Complete explanation
- Must be true, references are useful to validate the text.
- Put important information first.
- Be logical and sequential. Have no gaps in the logic. All steps should make sense to one another.
- Make no assumptions that the user will know or understand something, unless this is a prerequisite for all users.
Highly organised
- Divide into sections and subsections.
- First explain the simple aspects then go into more detail about the complex facets.
- Use ordered lists for your step-by-step procedure writing.
- Use parallel constructed lists.
- Use tables.
- Use flow charts to illustrate decision making processes.
- Use images with descriptions and place them adjacent to the text where they apply.
- Use links to connect related topics and sections.
Usability testing
- Test that the writing is understood as intended and rewrite until it is.
References
- ^ a b What are the features of technical writing?, Quora, 2017
- ^ a b Hints on writing style
- ^ Weasel and peacock words, Wikipedia:Manual of style.
- ^ What are the principles to apply in (web based) technical writing to effectively impart practical knowledge about the subject? answer by Ugur Akinci, Quora, 21 Jan 2020
- ^ Technical writing is different from causal writing. It involves certain basic techniques. Is this true? answer by Bradley Nice, Quora, 20 Jan 2018
- ^ What are the principles of technical writing?, answer by Andrea Mock, Quora, 4 September 2016
Further reading
- Letting Go of the Words: Web Content that Works by Ginny Redish, Morgan Kaufmann, 2007, ASIN B005NZ5K0W
- Every Page is Page One by Mark Baker, XML Press, 2013, ISBN 1937434281
External links
Examples
- Heathkit manuals, Archive.org