Skip to content

Latest commit

 

History

History
77 lines (52 loc) · 2.48 KB

technical-writers-guide.md

File metadata and controls

77 lines (52 loc) · 2.48 KB
contributors
Michael Karén, Lars Gyrup Brink Nielsen

Technical writer's guide

The title

  • Spend time on a good title.
  • Choose a good picture.

The beginning

  • The most important sentence in any article is the first one.
  • Present you article so it induces the reader to continue reading.

Be effective with your words

  • Avoid Redundant Phrases
  • Simplify, simplify
  • Review & Re-write lots of times.
  • Get rid of all the clutter.

Avoid assumptions

  • Don’t assume that your readers know what you assume everybody knows.
  • Don't assume that they still remember what was once explained to them.

Technical materials should shun words such as simply, obviously, and clearly in reference to the subject. These words, among other dismissive terms, add no meaning to your writing. Unfortunately, they do communicate that the topic should be easy, simple, or obvious.

Flow

Consistently short, medium, or long sentences create monotony. Add variety so that a piece doesn't become too choppy or too drawn-out.

Weak writing (passive voice)

Passive: The article was written by me. Active: I wrote this article.

Summary

  • Short version of a text that only contains the main points.
  • The main aim of a summary is to sum up the main points.
  • An executive summary is at the beginning of a document.
  • A summary should also have a conclusion.

Conclusion

  • The end or finish of a chapter or text.
  • The purpose is to conclude the text smoothly.
  • Is at the end of a document.
  • Can include a summary of the main points.

The ending

Next to the beginning this is the most important part. You should give almost as much thought to choosing your last sentence as you did to your first. What usually works best is a quotation. Go back through your notes to find some remark that has a sense of finality, or that's funny, or that adds an unexpected closing detail. A good ending gives the reader a lift, and it lingers when the article is over.

Headlines

Include self-interest into every headline. Self interest is a reliable way to make people care and as a result act on your message. Self-interest means that we make our headlines signal that there is something the reader wants.

Links

Books