Hi friend.

I am going to drum the quality drum again. This is a big topic and I know for a fact that I haven’t even scratched the surface of what there is to say about it.

About a month ago I wrote

I’d like to admit, I never had a mentor or teacher who showed me how to properly document software. It was all learning by doing. If you don’t mind, I’ll take some future episodes of this newsletter to document (see what I did there? 👅) my findings and further thoughts about this topic.

This is one of these letters about documentation. My knowledge hasn’t grown by as much as I would have loved, but I read some interesting articles about docs. I want to share these with you.

A beginner’s guide to writing documentation

The first thing should be this article from the resource “Write the docs” (a community of people who care about docs 😊 yes, that exists…): A beginner’s guide to writing documentation

This is a guide to documenting your first project. The first time is always the hardest, and I hope this guide will get you started down the righteous path. At the end, you should have a project that is ready for public release.

Who Writes the Docs?

Should all developers write docs as a matter of course? Is it even worthwhile having specialist writers? In this talk I’ll try to find some answers to these questions, based on my experience working in many teams - both in teams that have valued tech writing and in teams that haven’t. I’ll talk about the ‘documentarian’ mindset and how that contributes to better software, no matter what your job title is.

This is a video from a talk given by Beth Aitman at the Write the docs conf 2018 in Portland. So it’s rather recent.

I believe there shouldn’t be dedicated technical writers but that developers should write the docs. This helps in building empathy for the end users of our software.

Writing technical documentation when you aren’t a technical writer (series)

This series on Medium offers lots of insight on writing docs. The parts 1 + 2 from Taylor Barnett are a great start to get you going. It continues with documentation APIs. One important part of your docs.

Example API docs

These docs by Stripe are something like a (almost?) gold standard for docs. They are really good. Take example 😉

Alright that should be enough for a short introduction to your reading material. Queue it up in Instapaper/Pocket and let’s get better at writing docs.

Docs as code comments could be one of the next topics. Again, let me know what you think!

Yours, Holger