Member-only story
Modern Software Engineering – Part 3: Documentation
“I have only made this letter longer because I have not had the time to make it shorter.” – Blaise Pascal
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…
