Technical Writing

Why and how.

Susan Sons

IU-CACR Chief Security Analyst

and ICEI Hacker-in-Chief

In case you'd like to follow along.

But, I'm not a writer...

Writing is good for you anyway.

  • It's a high-demand meta-skill for hackers that comes with perks.
  • If you want to be understood, you must practice being understandable.
  • Writing well improves your thinking.

Your projects need writing skill.

  • Good documentation is essential for
    delegation, succession planning, onboarding, to assist users, and more.
  • It's how we prevent re-inventing the wheel in our fields.
  • Your writing can reach further than you can personally.

What should hackers be writing?

End-user documentation

Bug reports

Vulnerability disclosures

Technical and process manuals

Articles and blog posts

Emails, memos, and reports

Notes, handouts to back up your speaking

Sure, but how?

Writing is hard and I hate it!

The planning stage:

  • Know your audience
    • What do they want?
    • What do they already know?
    • What do they need to get where your piece is taking them?
  • Understand your purpose, keep it focused and concrete.
  • Break the topic down into smaller, easier-to-explain components.
  • Use a hook to start, and try to end with a call-to-action or (if teaching a broader concept) pointers to additional resources for next steps.

The words you use matter.

  • Focus on the audience's needs and wants, not yours.
  • Avoid jargon or other confusing language in most cases.
    • If learning jargon relevant to a field or specialty is important, then define on first use and consider adding a glossary if many terms are introduced.
  • Use correct grammar and spelling: most technologists think their English is "good enough", but often it falls apart when speaking to non-native speakers or even people from other English-speaking countries and regions.
  • Have someone less familiar with the subject than you read your work and provide critical feedback.
  • Have a technical expert check you on the facts.

The words you use matter, part II

  • Never insult someone by accident.
  • Give people the chance to look good.
  • Be more polite than is really called for.
  • Over-communicate rather than under-communicate, but never patronize.
  • If speaking to a busy or high-authority audience, be as brief as possible and include an executive summary.

The Art of Brevity

Practice that Makes Perfect

Do something about crumbling, insecure internet infrastructure

Questions/comments/etc welcome: