Help:Effective technical writing: Difference between revisions
Jump to navigation
Jump to search
no edit summary
(under construction) |
No edit summary |
||
Line 1:
This attempts to outline some basic principles for '''effective technical writing'''. How to communicate practical knowledge
== 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.
Line 18 ⟶ 22:
* Avoid making nouns from verbs.
* Try to balance comprehensive coverage without overwhelming with too much information.
* Use a [[Help:Article style|consistent familiar style]].
=== Complete explanation ===
* Must be true, references are useful to validate the text.
Line 25 ⟶ 30:
=== 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 ===
<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 ==
| |||