Technical Writing

Write simply

Consider your audience.

  • What are their goals and what is important to them?

Avoid jargon

When covering technical topics, there will be a tendency towards technical jargon: APIs, Containerization, Kubernetes, Memory bloat, SLAs, microservices, the list is endless. For your peer group who has full context, these are specific terms of art that save time and precisely label a concept or tool. For outsiders, this places a distance between the reader and yourself. In the innocuous case, it creates the need for explanation and definitions of terms. This distance turns problematic when jargon is used as a shield against inspection. Are you hoping that the reader will be to confused or harried to dig into that acronym or concept? Is the jargon being deployed to hide your lack of confidence in the underlying premise? If so, you must zap any unnecessary jargon.

Write confidently

Your goal is to communicate a set of facts, and then from those facts, an action recommendation. If you are not confident in your facts, you will likely need to do more work to confirm them. If you are not confident about your recommendation, then you can present alternatives. This can be useful in itself, allowing you to confirm your priors and think critically about your recommendation. However when you are confident, alternatives should be presented in the context of why you think yours is superior. Do you not hedge in your recommendation because alternatives exist.

Structure

  • Five paragraph essay from school
  • Target skim-ability

Think and then write

  • Writing clarifies thinking

Cheat

  • GPT
  • Pro Writing Aid, Gramarly

Links to this note