At work we’re looking to provide what we do as a platform, so that others can benefit from our ability to reach out and help communities. It’s highlighted something we’ve long known, but not really addressed. How we do what we do is poorly documented.
As with so many things, there’s a difference between quality and quantity. There are tools that automatically generate documentation, based on the code we’ve written. This seems an easy win – there’s a lot of output for very little effort. It’s high quality, too – it keeps itself up to date, is consistent and it’s easy to tailor what’s produced. Unfortunately, detailed technical specifications are of little value to the manager who needs a broad understanding of the system. Conversely, a high-level architecture diagram isn’t enough for the specialist looking to use an API.
We can’t start with what’s easy to produce. We have to start with what will bring the most value. We’re compelled to consider who we are doing this for and what they need.
Start with intent.