Culture
Technical documentation. How can I write them better and why should I care?
In this talk I’ll show you a structured way to write technical docs. Even if you’re not a technical writer you’ll be able to deliver highly valuable information to your audience, to the best of your ability. I’ll explain why you should care about these docs, how they serve your best interests (yes, there’s more than one!) and what impact they could have on employees and even your entire organization.
Talk abstract
I will walk you through a structured way to write technical documentation including:
- First, understand the audience. Then you'll be able to understand what should be covered in this documentation and to what extent.
- Build a skeleton table of contents. I'll share examples of what types of chapters and sub-chapters to include for several types of documentation.
- Start populating the contents, preferably during a project so things are still fresh in your mind.
- I'll share tips of how to write in a simple yet understandable way + more general writing tips
- Once the documentation is ready, give it to your colleagues to review and see if there's anything missing in their POV.
- Don't forget that documentation is not limited to a KB - you can add a readme.md in the repo detailing how to use the code you've written, etc. Documentation is for explaining anything at any point in time or place.
Key takeaways:
What to include in your technical documentation, and why should you care and invest time in writing them (spoiler: It'll lower your volume of support on other people, and much more), A structured way to approach technical document creation. You don't have to be a technical writer to write awesome technical documentation.
