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&rsquo;s required in Agile practices, or that writing design documents is not a good use of time. There&rsquo;s some truth to these sayings and it&rsquo;s usually because the documentation being developed isn&rsquo;t providing lasting value to the audience it&rsquo;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&rsquo;m reminded why it&rsquo;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&rsquo;t artists.</p> <p>In fact, there are so many skills involved in writing effectively that it&rsquo;s just not innate to someone trained in logic and precision when telling a computer to do something. If I personally didn&rsquo;t learn about nor try to excel at writing, I can easily see myself in the camp of &ldquo;read the code&rdquo; to understand what it&rsquo;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>