One of the odd discourses in our industry is the value of documentation1. The early documentation discourse was seemingly, “the more, the better.” This followed out of some early general patterns of software creation: One set of practitioners would design the algorithms, and another set would turn the algorithms and punch it into the code itself2. When the cost in human effort of creating punch cards and running programs was so large, it only made sense to write more documentation than the program itself.

As the cost of compilation decreased and we moved to more iterative forms of software development, our standards of documentation became more lax as well. Some practitioners in the agile space went past “working software over comprehensive documentation” to “an agile document is just barely good enough” as Scott Ambler writes.3 When I encountered my first truly monstrous documentation project, I fully agreed. When I was at Visa International in 2011 as a contractor, the lead for the project had written over 100 pages as a design document and there were weeks of meetings by business analysts to document every requirement that would be referenced in a UAT system. We had a parallel process that was more agile to get those projects out, but it still took significant work to create such comprehensive documentation as was standard for the process.

At Zipcar, by contrast, knowledge was shared from person to person for shared code context. If Visa had too much, Zipcar had far too little. There were entire swaths of code that fewer than three people understood, and they weren’t touched unless absolutely necessary. Even on new development, there were times where the only answer was to ask the person who developed it or to dig in and figure it out. 4 This was efficient when developing a feature in a familiar code base, but very inefficient when changing the system down the road. We tried to build a few sets of documentation along the way, and by the time I left we had some unevenly dispersed documentation.

I then went to OneStudyTeam (then known as Reify Health), where I saw a fully fledged functional documentation culture. I remember my first month asking if the behavior would be documented and a developer came to me in a 1:1 and told me, “Relax. We document everything appropriately and you don’t have to remind on every ticket.” This wasn’t fluff – it was true and it had been for years. They had successfully defined a documentation culture. Conversations in chat for clarification on how things worked were often redirected to existing documentation. The harder problem wasn’t that it wasn’t documented; it was that it wasn’t always updated and there was sometimes duplicate documentation because it wasn’t easy to search. Even so, I personally saw it save more time than it took to write the documentation.

The keys to OST’s documentation culture, in my view, was that there was a cultural expectation to document what you changed, there was existing prior art to have examples to show what good documentation should look like, and there was immediate value - people were able to see the value in their first 30 days as they read the existing documentation. This work, alongside pair programming sessions and a culture of helping others, allowed developers to get up to speed quickly on any codebase in the company.

There is a basic assumption is that most developers hate writing documentation. From my experience, this isn’t true. They don’t mind it, but they often don’t feel like they do it well, don’t feel like they are given the time to effectively document, and don’t see the value when they try to document. Assuming you have organizational buy-in, the best way to make it feel effective is threefold. First, build a proper framework on which you can attach the documentation for discoverability. Next, build examples of a good documentation style. Finally, build it into your definition of done at the feature level.

Ensuring management buy-in

Building a documentation culture takes time and effort, and you need to ensure that you are going to have an organization that believes this is an important initiative. Senior leaders (such as your CTO or VP of Engineering in a smaller organization, or a department director in a larger org) have continually competing priorities, and before building an effort to create change, you need to make sure that this is change that aligns with senior leaders’ understanding of current pain points.

Documentation has a return on investment, from my experience, but there are no wide-scale studies for which I am aware. However, senior leaders also can point you to the pain points they have, of which they may see as higher priority. If your vision does not align with theirs, your work will not be appreciated and your effort won’t bear fruit. I would start with this article to look at how to get buy-in to affect change, as it’s a large topic and outside the scope of this work.

Build an initial documentation infrastructure.

Assuming you have organizational buy-in, the first work is to build the framework on which your team’s documentation will rest. I feel like this is hard thing to do perfectly, but having a bad documentation infrastructure is still better than having none at all. People want to feel like there is a good place for their documentation to live. I see two major options for your documentation: The first is wiki-based software such as Notion or Confluence (which seems to have its hands everywhere, even if nobody likes it), and the second is to use source control and markdown.

The advantage of source control is that you have less flexibility in how to construct your documentation structure, as you are primarly in a tree format. This sounds like a disadvantage, but half of the battle of documentation is knowing where to put it in a way that is searchable. The disadvantage is that you will occasionally provide documentation for multiple audiences. If your audience doesn’t use github or your source control system of choice, they will not feel confident in searching your documentation. This is one place that backstage and TechDocs can help. If I were starting a documentation effort from scratch today, I would use TechDocs. That said, the key is to make a decision to start rather than get stuck in analysis paralysis. If Confluence is the only tool available, use it.

From there, I think it is important to speak to three types of internal documentation: people, process, and technology5. The key thing to consider here is that your people documentation and some of your process documentation is likely coming from people other than engineers, and process documentation may be split between systems. People documentation is largely HR-focused and is often created in Microsoft Word, but you don’t need to have “how to request vacation” in the same place as other internal documentation. However you should consider a single source of truth such that documentation doesn’t become bifurcated. Similarly, process documentation within engineering will mostly be built by managers with some exceptions, but it will often have interactions with technical documentation. It is also easy to bifurcate, but you need to be more careful because any choice made by a documentation writer is an opportunity for analysis paralysis and a stop to writing the documentation.

It is worth splitting the process into two types: there is process at an engineering department level, and there is process at a project level. Process at an engineering level should be grouped in one area: it will need its own space. However, projects and teams often have agreements that are separate from the engineering department: this is particularly common in agile teams with team agreements.6 The important part is that you need to have a space for this information, even if a team doesn’t use it. If you don’t have a space, it can be conflated with the technical documentation, making it harder to find that documentation.

Technical documentation, similarly, has department, vertical, and team implications, and may not match your project repository structure. Where it makes sense, split them into their own spaces within the larger tool. In a source control repo, it makes sense to have a separate repo for cross-functional concerns. This may have holistic documentation like Architecture Decision Records, and also may have more holistic architectural designs. (As an aside, C4 is probably the best option here for larger organizations but I still find it slightly complex for many use cases. I like Event Modeling for as long as you can get away with along with a high level architectural diagram. Event Modeling does not need to correlate with event sourcing in all cases.) The important piece here is to make a decision to match your team topology7.

For this documentation, consider creating a minimal documentation portfolio that specifies the documentation needed for project stakeholders and team communication. This documentation should serve the team rather than serve the project or organization and may be as simple as team onboarding materials, decision records made by the team, and copies of chat threads minimally cleaned up.

These are decisions that should start with a very small group and presented later, or you will end up with analysis paralysis. It is better to start with something wrong and adjust than get caught up in details. So long as you have a folder that roughly matches the topology, you can treat this documentation like a large sandbox to start. This sounds complicated, but there is no effective prescription here because team topologies are not standardized in this industry.

The final piece of documentation is long term project documentation. I am a strong proponent for the Diátaxis framework. The Diátaxis framework dientifies tutorials, how-to guides, technical reference, and explanation. Rather than dive too deep here, I’ll point to their great advice on how to use it. This often can live in your current repositories, but this depends on your team topology.

Build examples of a good documentation pattern

The second step of building a strong documentation is to build a pattern. Just like senior engineers build patterns for with other engineers are responsible for following, so too it is important to build examples of the documentation you are expecting others to follow.

I suggest taking these from external projects. I point to backstage as a great place to start. While it is external documentation, it is meant for developers and is quite copyable. Their getting started documentation is a great example of a tutorial. Their build system is a good example of explanation. They have a good example of bespoke API documentation, but you may be better off including that with a specialized tool like postman. For how-to guides, though, I will point to Indeed’s how-to guide on how to build how-to guides.

I have seen larger organizations provide style guides, but there is no good generic style guide I know of other than the suggestions at the end of each Diátaxis page. However, people will follow the guidelines that you show as an example long before they will internalize a style guide. However, what will be profitable is to have templates for people to start with.

A good documentation pattern and templates will not necessarily create good documentation as developers learn how to build better documentation, but the key is to be supportive as developers write their first documentation, knowing that successful documentation will be revised and refined as the project progresses. Unless entirely incomprehensible, enthusiasm will trigger better feedback loops than critique.

Build documentation into your definition of done at the feature level

Finally, once you have some good examples of documentation, the key is to build it into your process. This will require support from your champion more than the previous steps: this is where change actually starts. While in the long run, the return on investment in documentation will be high, it takes a lot of work to build those organizational muscles and to build the documentation corpus.

A common strategy in organizational change is to start with new initiatives, and only going back to previous initiatives as they are changed or on a risk-based basis. (For example, if the critical billing code is only understood by two people in the company, that’s a key risk to consider remediating with more than documentation!) As such, it helps to start with a single team that feels the same pain point and can be used as a pilot for gathering progressive buy-in. The most important contributor to success is to build documentation into the process. If documentation is an expected output for every work, it will become habit. While I would never suggest every feature or ticket needs substantive new documentation, the default should start as “on” until the right balance is found. (If you have documentation debt, every feature is an opportunity to address the surrounding areas of what is being touched.)

Further, use new team members to drive documentation needs. As people are approached to explain the system, these are key inflection points to drive remediation of documentation debt. At the same point, be brave enough to say that documentation has a cost both in writing and upkeep and do not write what is unnecessary, and archive or delete documentation that has fallen out of date.

Conclusion

There’s a cumulative wisdom in the industry on how to build technical documentation that hasn’t fully coalesced, but I am hoping that this gets people on the right track as they build their own documentation cultures. I didn’t touch on greater themes of change management and team buy-in, as these are better covered by this HBR article or this one. Once you have reached the collective buy-in, these are tools that I have seen help documentation efforts be successful.

Thank you to James Carr and Geoff Gallaway for initial eyes and comments.

  1. By “our industry,” I speak of software development in general, and by “documentation,” I speak in particular of internal documentation, the work we generate to explain our work to other practitioners. While I think this may also be valuable to consider in open source software, I am speaking in particular about software designed in a corporate context. ↩

  2. Richard Waychoff’s descriptions about those around the Burroughs B5000 mention an automatic programmer named Toni Schumann who facilitated arranging for computer time and getting programs keypunched. The gender issues there are for another blog. ↩

  3. The argument many agile practicioners make is that your unit tests should be your executable specification and that your time is better spent writing code that is self-documenting. While I agree that code, at its best, is self documenting and that the working definition of a unit test suite should be an executable specification of your system, unit tests explain the code at the smallest possible increment and do not explain why. They do not explain rejected alternatives. They do not explain why some code uses pattern A and some uses pattern B. Is that because of an incomplete refactor, or is it because of a limitation in an upstream library? If I start to refactor this code, will I get three days in and realize why the last three people have tried and failed? That said, Scott Ambler is a good representative of the counterargument and is worth understanding the balance. ↩

  4. Incidentally, this led to my most epic debugging session of my career. We had a new product for which I came on to the team. Nobody could figure out this billing issue that people would randomly be charged hundreds of dollars more than expected. This led me down the rabbit hole to five different code bases in four different programming languages and pairing with seven separate developers from five teams and eventually my manager, when we realized that one set of code was using “0” to encode when a state was changed, and the billing system was trained to ignore “0” because it encoded a separate state change that was normal in operation. There was no documentation in any of the scenarios that would alert to the situation. ↩

  5. Apparently, PPT comes from a 1964 paper called “Applied Organization Change in Industry” by Harold Leavitt. At the time, Structure and Tasks were split out into separate categories and have since been consolidated to process, and this work by Becky Simon for Smartsheet has some interesting context in the case you’ve heard this before. ↩

  6. This is not a particularly great example, but most team agreements are minimal anyway. ↩

  7. https://teamtopologies.com/ is where I found the term and it is described by a good book worth reading if you are in management. However, I mean to use this term more loosely. ↩