Writing effective documentation | Beth Aitman | #LeadDevBerlin

Documentation can make a big difference. Internal documentation can speed your team up and makes it easier for new engineers to get up and running. External documentation reduces time spent on support questions, and makes your product more usable.

But we often don't get round to writing documentation, because it's kind of a pain, and we don't know where to begin. So in this talk, I'll give a primer on writing effective documentation, and on helping your team to write docs too. Covering:

What makes documentation useful
How to make it easier to get started
How to make writing clear and readable

About Beth Aitman
Beth Aitman is a technical writer at Google, where she works to improve developer experience for Site Reliability Engineers. She’s interested in the intersection between UX and writing, and is passionate about teaching developers to write good docs. Outside of work, she likes to run around, climb rocks, and solve cryptic crosswords.

Lead Dev is a community for technical leaders. We have a series of conferences and meetups designed with the needs and pain points of technical team leads in mind. We programme each conference around our three key themes of Team, Tech & Tools. The talks are designed to help very practically with common problems in these areas. To find out more about us, visit:

[rushebshah]

1:05 start with what the reader needs
2:26 write less
4:05 write the outline first
5:19 rubber ducking
6:26 write readably
8:41 it's not just about documentation

[DodaGarcia]

This was so useful!! I have always ignored documentation (aside from inconsistent comments in the code) because I'm typically the only user, but I've recently realized that when you only use a piece of software every few months, you might as well be a total stranger to it because you have to relearn how all of it works each time.

This inspired me to document the API so that I don't have that extra friction next time I have to use the code. Thank you Beth!

[ErnestoCode]

Great speaker, loved the clean layouts of her slides, the simplicity is so elegant.

[ColbyCBoone]

This was super helpful, I’m a platform PM & writing documents for a technical audience has been challenging I’m looking to grow an improve in this area.

[kresnofatihimani]

swear to god, she's right. ive seen documentations with abundance in details but does not help much in achieving what i want which usually forces me to look immediately at a use case in a medium blog or something

[zenginellc]

This definitely helped in reflecting on my documentation styles and how to improve it.
Thank you!

[ngr]

Great talk! I love the last point. Often people try to mitigate the problem with documentation and don't try to solve the underlying problem

[roland]

Straight to the point and simply explained ❤

[taraspelenio]

Very good and structured description of base rules for creator of useful documentation

[nivasanbabusrinivasan]

Beautifully explained, I loved the point about friendly documentation!

[SamOween]

Thank you, I will use your technique to document my feature

[hamedahmadi]

great content and beautiful smile at the end

[MainlyWebStuff]

Nice talk - good advice, especially 'write readably'

[mosesket]

Does anyone have a sample doc like she explained here

[cthuloox]

@Beth Aitman This was a great video on this subject. I learned a lot. Thanks!

[goktugerol]

Nice, but I prefer writing the documentation of the things I make myself with the other Sr. engineers. Never worked with a technical writer, maybe I see some significant difference if I try. Is there anyone think as same as me?

[Amy-zzln]

Can you please help me know how to get Software documentation writer job as a fresher?

[preciousonyewuchi]

Does anyone know how to get a link to the blog she mentioned?

[raoulkoopman]

Anyone able to get the name of that blog?