Technical writing

Advice to new technical writers

Assuming that you satisfy the basic prerequisites of having basic writing skills and some rudimentary knowledge of the subjects you’ll be writing about, these three pieces of advice are the best I can provide:

Become an expert on the topic you are writing about

You need to have confidence in your understanding of the subject matter. Otherwise, use the product enough until you become an subject matter expert (SME) or collaborate with an SME who can help you complete your understanding of how the product works.

Write clear, concise English that non-native English speakers can understand

Do your readers a favor by writing simple sentences using the most common vocabulary for the subject matter. Long paragraphs consisting a single compound sentence are not pretty, even for native English speakers. When I proofread my first draft, I look for words that can be removed and compound sentences that I can break into simple sentences without changing the meaning. The best writing is the easiest to understand writing with the least number of words. Your readers want meaningful content, not fluff.

Develop a team mentality

Work with your fellow technical writers. If you see a fellow team member struggling with a task, offer your assistance. Documentation is mainly a team effort.

Don’t delay asking your team lead, manager, or product owner if the scope or acceptance criteria aren’t clear. Even if you feel you understand the acceptance criteria, it’s always good to share your progress with the reviewer early on to make sure you are on the right track.

Accept constructive criticism gracefully and learn from it. Give others constructive criticism in a respectful way without coming across as arrogant.

Tools

The following list of hardware, software, and services is what I feel most comfortable with. Enumerated items represent my order of preference.

  • Linux

    • Server: Ubuntu Server LTS

    • Desktop: Ubuntu or Linux Mint

  • macOS with M1 chip

  • Visual Studio Code

  • German keyboard

  • Git

    1. CLI

    2. GitLab

    3. GitHub

  • Markup

    1. AsciiDoc

    2. Markdown

    3. \(\LaTeX{}\)

  • Static Site Generators

    1. Antora, because it can read directly from remote Git repositories and has a separate front-end development environment Antora-UI for the design team

    2. Docusaurus

  • Cloud

    1. Amazon AWS
      (my oldest S3 buckets are from 2009)

    2. Microsoft Azure

  • Project Management

    1. Pivotal Tracker
      (sadly, most employers are in love with Atlassian products)

    2. Jira