5 steps for writing architectural documentation in a code-focused culture

Architecture is all about designing the shape of a system—what are the components, how do they interact, what data comes in and out? It can be an incredibly visual task with whiteboards and sticky notes, or it might be deeply nuanced with protocol specifications and hardware requirements. It can also include writing API schemas, experimenting with new technologies, and prototyping a minimum viable product.

Finding the right balance between documentation and implementation is part of an architect's job. But what do you do if your culture values implementation a little too much? How can you provide documentation that both your immediate internal users and eventual external users need to be successful?

Here is the funny thing about documentation: Even in environments where it's considered a nonessential task, no one will complain once it's done, so long as your "technical tasks" are also complete. In fact, I've found that the right documentation can receive a lot of recognition in code-focused cultures from folks of all seniorities. And public praise of documentation can begin to turn the tide on the culture as a whole because leaders can point to your team's or product's documentation and say, "I want that too."

How to bootstrap documentation in a code-focused environment

When I start on a new team that needs documentation, I follow these steps:

1. Don't write docs

Start with this nominal approach because not writing docs is the status quo. If there is a specific deliverable that your peers or leadership are waiting for you to complete, it won't be acceptable to hold this up before you've cracked open the culture. This is true for both new team members who haven't built up street cred and senior contributors responsible for a high-value task. Be cognizant of the amount of slack you have in the current assignment.

2. Choose an accessible medium

When you do find the opportunity, start thinking about the logistics of your upcoming documentation project. There may not be an obvious place to put your new content in an organization that doesn't put much stock into docs. Confluence, GitHub or GitLab wikis, READMEs or other plain-text docs stored with the code, and PDFs built with Sphinx can all work. Choose something that your teammates and leaders know how to find on their own. It's okay if this resource is currently undervalued—you're going to add content that changes that perception—but it's going to be harder for you if the documentation isn't self-service.

[ Learn how IT modernization can help alleviate technical debt by downloading the whitepaper. ]

3. Start with frequently asked questions

Answering questions with written documentation or quick illustrations is my definition of just-in-time documentation and my favorite way to start creating documentation organically. If you're answering a question from a colleague or customer, it won't take very long to add a little formatting, double-check grammar, and post it somewhere your team can access. Just don't spend too much time toying with your medium's macros and advanced formatting at this point. When you're done, post it in chat or email it to colleagues who might have, or have to answer, the same question.

There's some time between the last step and the next one. In step 3, you build out a useful but reactive documentation resource. To get to a proactive documentation resource that can preempt an inquiry, you have to understand how your users navigate your product (and, therefore, where they get stumped) and how they approach the documentation. Listen to the feedback. If you receive a question you've already answered in the docs, why couldn't they find it? Would adding tags help? Hierarchy? Do the section headers match your users' jargon? Are they just looking for snippets to copy and paste?

Image

It can be frustrating when you spend time on a written solution that no one reads or sequence diagrams that no one reviews, but don't take it personally. Remember, you are introducing a new variable into the ecosystem. Consider your new documentation an experiment. Measure the response and course-correct as necessary. Don't proceed until you see some traction with the FAQ.

[ Plan your next cloud project based on your current cloud results by downloading the 4 essential cloud project questions checklist. ]

4. Abstract, codify, and organize

Once you know how to build docs that your users can appreciate, start formalizing the documentation for the components that yield the most questions. Note that this isn't necessarily the same as the most-used components—people may understand those well, so it won't be perceived as providing as much value. If there's no clear frontrunner, I usually start where the user will: installation and setup. Provide these new docs when you hand off your architecture or when you hear a user will soon be needing the feature you documented.

5. Maintain the process

Don't let people lose faith in documentation by allowing it to become outdated and inaccurate. I've found that the closer you keep the docs to the implementation—including in the very same code repo, if applicable—the better chance they will stay up to date. When docs reside with the code, both can be updated in a single pull request instead of docs being an afterthought. Don't be afraid to build docs from the code if it makes sense. In any case, review the documentation periodically, prioritizing sections that document rapidly changing components.

Keep your experiment going and iterate on your documentation as you would iterate on your architecture. Share your insights with teams who want or need to bootstrap their docs. Can architects write docs in your organization without feeling anxiety? Are they expected to? Do they want to? Hopefully, you will begin to see movement on this spectrum.

Deliver what's needed

Finally, remember that some of your teammates and leaders started out in that code-focused culture. In stressful situations, they may revert back to a comfortable known state where code resumes its role as the only accepted currency. That means they have little to no patience for time spent on the docs. Read the room, and deliver what your team needs now.

This article is based on How to write documentation in a code-focused culture on Evan Stoner's blog and is republished with permission.