Technical writing is a crucial skill for software engineers. Clear documentation helps teams collaborate, onboard new members, and share knowledge effectively. My skills in this area have become a little degraded (assuming I had them in the first place) in recent years, and this is a good time to refresh them. (Now is better than later or never, right?)

Resources

The Google Technical Writing Course is an excellent starting point. It covers:

  • Principles of clarity and simplicity
  • Organizing technical documents
  • Writing effective instructions and explanations

Other resources to look into include:

  • Microsoft Writing Style Guide
  • Write the Docs Guide
  • “The Elements of Style” by Strunk and White: A classic guide to writing clearly and concisely.
  • “Docs for Developers: An Engineer’s Field Guide to Technical Writing” by Jared Bhatti, and others: A practical guide for engineers on writing documentation.

Tips for Better Technical Writing

  1. Know your audience: Tailor your writing to their experience level.
  2. Be concise: Avoid unnecessary words and jargon.
  3. Use examples: Illustrate concepts with code or diagrams.
  4. Structure logically: Use headings, lists, and sections.
  5. Revise and get feedback: Review your writing and ask others for input.