Better Programming

Advice for programmers.

Follow publication

Member-only story

Modern Software Engineering – Part 3: Documentation

Dean Michael Berris
Better Programming
Published in
13 min readJul 2, 2023

Photo by Taylor Flowe on Unsplash

Documentation is a perennially controversial topic because, in my experience, software engineering has focused so much on the business value of artefacts like the source code and shipping features more than others. I constantly hear folks saying that we should only be writing the documentation that’s required in Agile practices, or that writing design documents is not a good use of time. There’s some truth to these sayings and it’s usually because the documentation being developed isn’t providing lasting value to the audience it’s meant to serve.

When I hear another software engineer complain about bad documentation that someone else wrote, I keep thinking about why we bother writing them at all. Sometimes though I come across very well-written documentation that I’m reminded why it’s worth doing. Unfortunately, this points out something potentially obvious to a lot of people but may not be obvious to some: documentation is more an art than a science, and most software engineers aren’t artists.

In fact, there are so many skills involved in writing effectively that it’s just not innate to someone trained in logic and precision when…

Create an account to read the full story.

The author made this story available to Medium members only.
If you’re new to Medium, create a new account to read this story on us.

Or, continue in mobile web

Already have an account? Sign in

Dean Michael Berris
Dean Michael Berris

Written by Dean Michael Berris

Principal Software Engineer at Microsoft by profession, writer by passion; thoughts are my own.

Write a response