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.
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?
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.
3. Good commit messages
4. Architectural and design decisions
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.