Help:Effective technical writing: Difference between revisions

Jump to navigation Jump to search
Content added Content deleted
VisualWikitext
(under construction)
 
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
This attempts to outline some basic principles for '''effective technical writing''' to communicate practical knowledge. Technical writing is describing complex subject or complicated procedure and breaking it down to make it understandable.<ref name="what">[https://www.quora.com/What-are-the-features-of-technical-writing/answer/Jamie-James-35 What are the features of technical writing?], Quora, 2017</ref>
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.<ref name="what">[https://www.quora.com/What-are-the-features-of-technical-writing/answer/Jamie-James-35 What are the features of technical writing?], Quora, 2017</ref>


== Key features ==
== Key features ==
=== Collaborate ===
* Technical documents are hardly ever written alone.
* Ask the experts.
=== Clear communication ===
=== Clear communication ===
* Put yourself in the readers place, write appropriately for your intended audience.
* Put yourself in the readers place, write appropriately for your intended audience.
* Use real world examples that your audience will understand.
* Use plain readily understood words.
* Use plain readily understood words.
* Use words with unambiguous meanings.
* Use words with unambiguous meanings.
Line 18: Line 22:
* Avoid making nouns from verbs.
* Avoid making nouns from verbs.
* Try to balance comprehensive coverage without overwhelming with too much information.
* Try to balance comprehensive coverage without overwhelming with too much information.
* Use a [[Help:Article style|consistent familiar style]].
=== Complete explanation ===
=== Complete explanation ===
* Must be true, references are useful to validate the text.
* Must be true, references are useful to validate the text.
Line 25: Line 30:
=== Highly organised ===
=== Highly organised ===
* Divide into sections and subsections.
* Divide into sections and subsections.
* First explain the simple aspects then go into more detail about the complex facets.
* Start with a general outline and explain towards more specific details later on.
* Use ordered lists for your step-by-step procedure writing.
* Use ordered lists for your step-by-step procedure writing.
* Use parallel constructed lists.
* Use parallel constructed lists.
* Use tables.
* Use flow charts to illustrate decision making processes.
* Use flow charts to illustrate decision making processes.
* Use images with descriptions and place them adjacent to the text.
* Use images with descriptions and place them adjacent to the text.
* Use links to connect related topics and sections.
* Use links to connect related topics and sections.
=== Usability testing ===
⚫
<ref name="what"/><ref>[https://www.quora.com/What-are-the-principles-to-apply-in-web-based-technical-writing-to-effectively-impart-practical-knowledge-about-the-subject/answer/Ugur-Akinci 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</ref><ref>[https://www.quora.com/Technical-writing-is-different-from-causal-writing-It-involves-certain-basic-techniques-Is-this-true/answer/Bradley-Nice Technical writing is different from causal writing. It involves certain basic techniques. Is this true?] answer by Bradley Nice, Quora, 20 Jan 2018</ref>
* Test that the writing is understood as intended and rewrite until it is.
⚫
<ref name="what"/><ref>[https://www.quora.com/What-are-the-principles-to-apply-in-web-based-technical-writing-to-effectively-impart-practical-knowledge-about-the-subject/answer/Ugur-Akinci 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</ref><ref>[https://www.quora.com/Technical-writing-is-different-from-causal-writing-It-involves-certain-basic-techniques-Is-this-true/answer/Bradley-Nice Technical writing is different from causal writing. It involves certain basic techniques. Is this true?] answer by Bradley Nice, Quora, 20 Jan 2018</ref><ref>[https://www.quora.com/What-are-the-principles-of-technical-writing/answer/Andrea-Mock-1 What are the principles of technical writing?], answer by Andrea Mock, Quora, 4 September 2016</ref>


== References ==
== References ==
Line 37: Line 45:


== Further reading ==
== Further reading ==
* ''Letting Go of the Words: Web Content that Works'' by Ginny Redish, Morgan Kaufmann, 2007, ASIN B005NZ5K0W
* ''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
* ''Every Page is Page One'' by Mark Baker, XML Press, 2013, {{ISBN|1937434281}}


== External links ==
== External links ==
Line 47: Line 55:


[[Category:Help:Editing]]
[[Category:Help:Editing]]
[[Category:Meta]]

Latest revision as of 11:45, 18 July 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

  • Put yourself in the readers 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.
  • Use short sentences 15 to 25 words on average.
  • One sentence per idea.
  • Break the text up, one concept per paragraph.
  • Use plenty white space in between the sentences.
  • Use the active voice.
  • Do not use adverbs aka weasel and peacock words.
  • Avoid making nouns from verbs.
  • Try to balance comprehensive coverage without 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 and all steps should make sense to one another.
  • Make no assumptions the user will know or understand something, unless this is a prerequisite from 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.
  • Use links to connect related topics and sections.

Usability testing

  • Test that the writing is understood as intended and rewrite until it is.

[1][2][3][4]

References

  1. ^ a b What are the features of technical writing?, Quora, 2017
  2. ^ 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
  3. ^ Technical writing is different from causal writing. It involves certain basic techniques. Is this true? answer by Bradley Nice, Quora, 20 Jan 2018
  4. ^ 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

Retrieved from "https://sdiy.info/wiki/Help:Effective_technical_writing?oldid=17726"