fbpx Skip to content

Another Way to Think about Technical Documentation

Hello! My name is Mina Demian and I am a consultant here at One Agency. Primarily a front-end developer, I have been moving towards full-stack development in recent times.

A few weeks ago, I delivered a lightning talk at our O/A Speaker’s Corner about some methods I have used lately to write technical documentation. Obviously, everyone just loves documentation and everyone just drops everything to write documentation.

😀

My case was that breaking down the idea of documentation into simpler concepts makes it less of a scary unknown and more of an achievable goal.

Big Idea

If we look past our usual excuses about writing documentation, that we’re drowning in stories or that it’s not a priority right now, the uncomfortable truth often lies in that we just don’t know _how_ and _what_ to document.

Think about that for a second. Try to remember a project you’ve been on or a company you’ve worked at, where someone directed you to some physical or digital documentation, and you just went, ”Wow! This is so good.”

It’s hard, huh?

My experience has been that “someone else, somewhere else” is good at documentation, like Stripe or CodeIgniter. But it’s rarely been the work of the place where I’ve worked at.

A New Way of Approaching Documentation

The following areas can provide a good coverage of the technical documentation of a software product or project. Goodbye 300-page requirement specification documents and outdated comments; say hello to 7 broad areas to work on.

1. Changelogs

2. Todos

3. Good commit messages

4. Architectural and design decisions

5. DEVELOPING.md

6. README.md

7. Comments

The first four categories can be wholly automated or simplified using tooling, while the last three are best done with manual labor.

These 7 areas capture the most important aspects of a software product or project.

Interested in More?

Check out the presentation! If you found this useful, we’d love to hear from you on social media. You can also send me any feedback on Twitter.