Modern Software Engineering – Part 3: 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>