Building Teams with Documentation
A Practical Guide To Technical Documentation
This article looks to outline a set of principles that, if followed, will tie quality documentation into your teams existing workflow to create scalable software, professional products, and efficient Software Engineers.
Introduction
Software Engineers from across the globe, industries, and disciplines have various job descriptions and workflows — but almost unanimous share a single common pain: a lack of quality documentation. This article looks to outline a set of principles that, if followed, will tie quality documentation into your teams existing workflow to create scalable software, professional products, and efficient Software Engineers.
Why Documentation?
Fundamentally, project teams are more focused when their design goals are clearly stated. A Software Engineer in consulting for example, is often thrown onto an existing project. No matter the experience of the consultant, there is a learning curve that takes place during this process. When a repository of documentation has been established, the newly on-boarded member can easily digest the existing code-base and thus understand the processes at play.
Authoring documentation itself is a tedious task to complete. There is no immediate benefit to writing documentation as the author, so why bother? Documentation tends to require much up-front effort and doesn’t provide clear benefits until later in the Software Lifecycle. It can be thought of as an investment. Think how long will the project be supported: 1 Year? 5 Years? 10 years? Now think how many times the author of a code feature might have to explain how that feature works over that time. As an author of documentation, we simply write a document once, but over its lifetime it may be read hundreds or thousands of times. Some benefits are as followed:
- It Helps formulate an API: If you can’t explain it, you probably haven’t designed it optimally.
- It provides a historical record: With a document, one can easily build off code that was written 1–2 years ago without fear of breaking the application downstream.
- A more professional end product: A product that has good documentation is usually a good indicator of how well a product will be maintained.
- It will prompt fewer questions. If you must explain something more than once, it usually makes sense to document that process.
Agile’s Myth
In the Agile Manifesto, one of the core principles is explicitly stated as:
Working software over Comprehensive Documentation.
This manifesto has led to interesting interpretations over the years. Some to go as far as documentation is not needed. The original authors clarified that their principle meant “That is, while there is value in the items on
the right, we value the items on the left more.” Simply put, its better to ‘do’ rather than to invest time in a overly detailed upfront documentation.
It is a myth that Agile methodology meant “Documentation is not important”. Agile is a philosophy to make projects more dynamic, because a project will inevitably change requirement scope over a duration of time. There is nothing in the Agile development methodology that inherently prevents us from creating as much documentation as the project requires. Agile suggest that documentation should be “good enough” not that it is a waste of time. To not waste time, ask the following set of basic questions:
- What is the document needed for?
- Who is the target audience of the document?
- How will the target audience use the documentation? As a Reference? As a Manual?
- How much time will it cost to produce?
Documentation As Code
When creating software products, a Kan-ban board (Jira anyone?) is used to outline tasks and distribute ownership to developers. This process is a tried-and-true way of optimally producing software. But what about documentation? Who on the team is responsible for producing the documentation in this workflow: Business Analyst, Tech Leads, Managers? Documentation should be treated as code — and thus — produced alongside code by Software Engineers.
Although Tech Leads and Managers can produce the documentation themselves, this strategy fails to scale well over time if more developers are added onto the project. Business Analysts can scale with the project but may struggle to accurately describe the technical processes that are taking place with each feature change. This leaves the engineers themselves to write documentation.
Tying back to the original point, Kan-ban boards are used to distribute ownership to tasks being created. The same distribution of documentation needs to be explicitly stated across developers to keep documents from becoming stale and difficult to maintain.
Clarity in ownership allows developers to incorporate documentation into their existing workflow while simultaneously preventing duplicate documents. Documentation is often so tightly coupled to code that it should be essentially treated as code. Which means it should:
- Have a symmetric structure
- Be placed under source control
- Have clear ownership
- Be periodically evaluated (or tested some way)
Industry Pains
When projects initially begin, tracking of files is seamless and manageable. Documents are added to a Microsoft Teams folder structure, attached to user stories in Jira, or hosted on other third-party applications. As time goes on, folder structures get more complex. People leave. Documents become obsolete or lost. New developers then join a project, and are never presented these lost documents, or can’t confirm if the documentation being presented to them is outdated or accurate. Before long, sprint burn down charts become increasingly stagnant and sprint goals are missed. The consequences of a bad repository of documentation leads to an inefficient on-boarding process, repeated conversations between stakeholders, and a ‘one-person-knows-all’ effect.
Obviously, this doesn’t happen for every project, but it does happen to some. How can this problem be mitigated? By writing documentation in Markdown (.md). Markdown has arrived as the premier way to write technical documentation over recent years. Documentation that has been written in markdown can be uploaded to a source-control repository (github, azure devops), is lightweight, can be easily edited, and above all is consistent. Collaboration is more obvious with defects being raised when documentation needs revisions. Overall, the process of maintaining documentation within source control provides developers with a similar experience they are already used to. This technique leverages an existing workflow, rather than attempting to create a new one.
Conclusion
A quick summary of this practical guide was to bring awareness to documentation by demonstrating:
- The benefits of documentation
- The steps to produce meaningful documents
- The strategies to instill ownership
- The tools to maintain documents
Documentation is something easy to look over. What the customer wants ultimately is a quality product — not a pile of documents. A quality product doesn’t just spawn into existence, it’s a journey. The journey to a quality product starts with a quality team, which can be built off of documentation.
References
This article was inspired by Titus Winters, Tom Manshreck, and Hyrum Wright from their book: Software Engineering at Google, Lessons Learned from Programming OverTime.
