Why and how.
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?
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
[NewGuard ProDev] Technical Writing
By Susan Sons