From an environment perspective, having solid documentation supports stability and productivity. So let’s tackle a tough question: What makes good documentation?

First off, there's no such thing as perfect documentation—just like there's no perfect code. The key is producing and maintaining it consistently. Documentation requires a different thought process than coding; it's more creative and explanatory.

AI Summary provided by Audiopen.ai, the only AI tool I pay for (affiliate link)

This brings me to the Diataxis framework. It categorizes documentation into four types: how-to guides (practical steps for tasks), tutorials (learning-based steps), references (quick look-ups for APIs), and explanations (theoretical understanding). This framework helps determine what kind of documentation is needed based on its purpose.

Diataxis helps organize information but doesn’t dictate where it should live—that's up to each organization. It’s like agile processes; each team adapts it to their needs.

So does Diataxis provide insight into organizing documentation?

Not directly; it focuses more on categorizing content rather than structuring it within an organization. Each team must figure out their own system based on their dynamics.

You mentioned implementing a documentation council at work. How does that function?

Our council consists of representatives from each feature team who audit existing documentation and handle requests for new docs or updates. We meet periodically to review what we have and what’s needed, creating tickets for updates or new documents as necessary.

When someone requests documentation, how does that process look?

We kick off audits once every quarter or six months, review existing docs for relevance and accuracy, then create tickets for necessary updates or new documents based on feedback from teams.

In fast-paced environments like Dynamit, how would you implement such practices?

It’s challenging but crucial to allocate time for documentation even in fast-paced settings. Managers need to push for this time allocation while developers should embrace professionalism by thinking about future maintainers of their code.

How do you balance code comments versus external documentation?

Consider who will consume your code: API layers need explicit docs while feature teams might need detailed comments within the code itself. Capture feedback during onboarding to continuously improve your process.

If you don’t have a council yet, where do you start?

Start small by identifying passionate individuals who care about clarity in their work. Give them responsibility over documentation as part of their career growth trajectory—it’s low stakes but high impact.

Thanks for sharing these insights, Michael!

It's not something your end user will see, but it provides juniors and mids with tangible tasks to demonstrate leadership abilities. For others, it's an opportunity to improve things, which is a common goal. Junior engineers, curious about the code and still learning, might notice a lack of documentation. They could spend a day or two diving in, understand it, and present their findings to the team.

I've noticed a trend in organizations heavy on Slack or Teams using video for documentation. Tools like Loom allow for recording changes and explanations. Historically, we preferred written documentation as a contract with everyone. However, long documents can be overwhelming. A five-page document feels like a wall of text; even I struggle with comprehension without multiple reads. TLDRs help in understanding the core quickly.

Videos as documentation are great but come with challenges. Tech talks at our organization contain valuable information, but making them accessible and searchable is tough. Tools like Microsoft Stream offer solutions by uploading videos, generating transcripts using AI, allowing comments, and deep linking to specific sections. This makes videos searchable and collaborative.

AI tools are evolving to assist in documentation. Tools that grok APIs and generate documentation or transcribers like Otter that take meeting notes are helpful. AI tools can retrieve information efficiently but should be used cautiously for generating content.

The industry's direction seems to favor tools like Microsoft Stream becoming more available. Properly cultivated video documentation can be as essential as written docs for quick reference and communication.

As for AI tools in documentation, they can create knowledge bases isolated from the public domain. Integrations with platforms like Confluence make information retrieval easier. However, I caution against relying on AI for generating content; it's better suited for retrieval.

While AI can cover up issues instead of fixing them, we must scrutinize its output rigorously. Use AI as a tool without letting it replace human judgment.

Documentation is an investment for the future and those who will replace you eventually. For new engineers, taking extensive notes while learning can form useful documentation later. It's about professionalism and continuous improvement—start small, iterate, and build a documentation culture.

In summary: dedicate time to documentation, use frameworks like Diataxis for guidance, leverage AI as a tool (not a replacement), and focus on continuous improvement.

For further questions on documentation, I'm available on LinkedIn.

This is a public episode. If you would like to discuss this with other subscribers or get access to bonus episodes, visit hartleyshandbook.com

#8 Documentation and the Council of Elders