Skip to content

stevegrunwell/write-some-docs

Repository files navigation

Still from the 1971 "I'd Like to Buy the World a Coke" advertising campaign I'd Like to Write the World Some Docs

It takes a special kind of person to enjoy writing documentation; not only do I have to write [ideally] working code, but now I have to write words that a human being can understand? What is this madness?!

Luckily, good documentation lives on outside your codebase. By following common documentation standards, we can generate comprehensive manuals that instruct others how to integrate with our software. After all, to code is human, but to document is divine.

View slides

Four panel comic from Commit Strip, with a conversation between two engineers: First engineer: "Hey, I got assigned some bugs on your latest project but it looks like there's no documentation?" Second engineer: "What? Of course there's documentation! There's definitely a readme and there are some explanations on Jira. And maybe some explainers in Trello. And there's some information in Google Docs in a shared folder. Check if you can access it. It's not really up to date, but it's probably useful. And worst case scenario, there are plenty of contextual comments in the code." First engineer: Okay, so exactly what I said then...there's no documentation."

Presentation History

Resources

Tools and Services

Notes