Adrienne is Currently a Senior Developer Advocate for MongoDB, Adrienne Tacke is also a Filipina software engineer, speaker, published author of the book Coding for Kids: Python, and a LinkedIn Learning instructor who specializes in Cloud Development courses. Perhaps most important, however, is that she spends way too much money on desserts and ungodly amounts of time playing Cyberpunk 2077.
Documentation: The Missing Pieces (A workshop on how to write better technical content)
Document all the things, they say! But are we documenting for ALL the PEOPLE? It seems that most documentation is written for the intermediate and above devs, the devs who have been around, and the devs who are already comfortable with programming.
But what about the true beginners, the career-transitioners, or those crossing domains? Most documentation is certainly not written for them!
In this workshop, we’ll explore
— Common oversights and assumptions most documentation has built-in by default
— Techniques that make our documentation more approachable for all kinds of people
— How to strengthen our technical writing skills to ensure, to the best of our ability, that every anticipated reader of our documentation never feels lost or frustrated.
By the end of this workshop, you’ll leave and never write documentation in the same way again…and that’s a good thing!
Part 1: What makes good (and bad) documentation?
- Discuss sample content brought in by participants
- Defining “good” documentation
- Common happy points
- Sources of value
- Defining “bad” documentation
- Common pain points
- Common biases
- Sources of confusion
Part 2: Elements of Ideal documentation
Part 3: Hands-on task: Making existing documentation better
- Making our “bad” documentation samples better
- Finding the pain points
- Finding the biases
- FInding the sources of confusion
- Reword, rephrase, rewrite, or rework
- Reviewing our improvements
Part 4: Hands-on task: New technical content
- Create a new piece of documentation that is made for beginners
- Create an “advanced” version
- Explaining how humans work (surprise activity)!
The main goal of this workshop is for participants to write better documentation and technical content. We’ll do this by identifying any weaknesses/biases they may have when writing technical content and learn to combat them using techniques meant to make technical writing easier and more approachable.
The target audience is anyone who has ever written any kind of technical documentation, tutorial, or blog post. This includes anyone who may be seasoned in writing this kind of content, but would like to improve their craft even more.
- Any IDE that supports Markdown
- Basic programming knowledge
- Bring two examples of technical content:
- A piece that you feel exemplifies what a perfect tutorial/piece of documentation is
- A piece that you feel is a terrible tutorial/piece of documentation