Modern Software Engineering – Documentation
<p>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.</p>
<p>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.</p>
<p>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 telling a computer to do something. If I personally didn’t learn about nor try to excel at writing, I can easily see myself in the camp of “read the code” to understand what it’s doing and not bother with comments or any other forms of documentation. But I have, in my ~20-year career as a software engineer, found that the well-placed comment to explain why something is implemented a certain way, or a document describing the trade-offs made where other approaches were rejected, saved me so much time and bother in getting up to speed and making changes to the code base.</p>
<p>And there, friends, is where the value lies.</p>
<p><a href="https://betterprogramming.pub/modern-software-engineering-part-3-documentation-e4978192e1cf">Visit Now</a></p>