Documentation. The word elicits many responses. In the corporate software development world it is the thing that everyone wants. It is how new team members get up to speed. It is how architects communicate with others about how to do integration.
I’ve been on a number of projects that have cycled through the usual set of practices with internal documentation. Someone makes some powerpoint slides to convey a ‘vision’, then translates that into word docs. Maybe eventually someone starts putting things into Confluence or the like to provide more details. All the while, developers are writing code, facing challenges, and making adjustments. Projects that have lasted for a while will have documents spread around in various locations in various states of accuracy. The old adage about a stopped clock being better than a clock set wrong because right twice a day applies to documentation.
No documentation is better than incorrect documentation.
While in college, I started working with LaTeX - and no, I’m not going to say that LaTeX is the answer to all documentation problems. But what it introduced me to was working with documentation the same way I work with code. This became especially useful when working on a team with each of us responsible for different aspects of the docs. It all made sense, and we mostly were able to focus on the content and the project without worrying about how to put all of the docs together to submit for the class.
Imagine my surprise when, in my first job after school, we spent so much time working on pulling documents together from different authors in Word. Everything was done out-of-band with code changes. Screenshots often had to be updated to reflect minor UI changes. It was a mess.
Since then, I’ve worked to evangelize the possibilities of working with documentation in the same manner as we do our code. I find it surprising that the concepts are still not known to many in the field. I think most people are familiar with Markdown, asciidoc or another at this point - but they are often overlooked as ‘serious’ tools for documentation for some reason.
In an effort to help with the discoverability problem, I want to reference Write the Docs. There is more than one way to approach an improved workflow with docs. But know this: it is possible to have documentation for a product change be included in the feature development, review, and deployment processes. This keeps the documents in lock-step with the code it is documenting. Reviewers can see the design concepts that drove development along with how to use the new feature while they are reviewing the code. Once published, the documentation artifacts are updated (and versioned) along with the code base. What is not to love about the simplicity?
At some point, I hope to write more specifics about what I’ve seen work really well in this space. If you’re interested, reach out!