The long-term trend toward Agile project management practices places a huge premium on eliminating wasteful overhead. Projects are moving faster than ever, and it’s easy to label documentation as a workflow that produces little value compared to producing more quality code.
In this context, documentation is often targeted as an activity that should be cut back. In fact, “working software over comprehensive documentation” is a key rule for Agile management.
This thinking, however, can be a trap. Documentation provides real long term value:
Key Benefits of Quality Software Documentation
- Carefully documented project requirements help keep a project organized, on-budget, and on-time.
- Quality documentation helps ensure that future development work can hit the ground running, ensuring your software product is a flexible long-term asset.
- Good documentation facilitates an optimal handoff from the development team to the team who will be actively managing the application (whether it’s consumer-facing, B2B, or internal).
- Selective, fit-for-purpose documentation preserves the flexibility of Agile development while ensuring changes stay tied to a plan that will ensure the fulfillment of core requirements.
There’s no doubt that Agile is pushing away from a rigid focus on exhaustively documenting every feature and coding decision. And, to reflect the dynamism of Agile development, modern documentation practices need to be adaptable on the fly.
But the ultimate need for quality documentation hasn’t gone anywhere.
In this post, we break down software project documentation and provide some insight into adopting a value-driven approach. We start by identifying a few high-level categories of software documentation below.
Key Aspects of Project Documentation
- Requirements
- Architecture/Design
- Technical
- End-User
Software Development Documentation: Requirements
Well-documented requirements help ensure effective cooperation and clear communication as developers work to translate business requirements into technical specifications.
Requirements should clearly define what needs to be done, alongside a reasonably precise understanding of what the completed task should look-like. A software requirements document should reflect both functional requirements and non-functional needs (like performance and failover capabilities).
In an Agile setting, requirements often originate as user stories. But the precise technical approach for supporting these user stories in the final software product may change over the course of the project.
A flexible approach allows for quick and easy implementation changes during the product development process. Requirements documentation should never try to restrain this flexibility, only to make sure that this fast-of-pace of changes is well-tracked.
Project managers play a key-role in ensuring that all stakeholders understand how changing requirements will affect the overall project. A flexible approach is great, but it can’t be allowed to push the app off-course from achieving its central goals (while staying on-time and on-budget).
For outsourced development teams, the relationship between requirements changes and project scope will depend on the contract employed. If development is based on a fixed scope, requirement changes will need to be reflected in the SOW. For a time-and-materials contract, the Project Manager can focus on the practical impact of requirements changes: “we can add this feature,” for instance,” but it will require either three extra weeks, one extra developer, or shelving another feature for this iteration of the product.”
For a deeper look at different development outsourcing models, we recommend our blog here.
Software Development Documentation: Architecture/Design
Software architectural documents are used to keep track of the highest-level decisions made about the structure and the behavior of the system. This documentation needs to not only track requirements, but how solutions have to be implemented.
Examples of architectural and design documentation include:
- Wireframe Diagrams
- User Interface Sketches
- Topology Descriptions
- DevOps Information
Software Development Documentation: Technical
Technical documentation captures program code. Such documentation includes:
- API descriptions
- Lists of Environment Variables
- ReadMe files
It’s no surprise that programmers don’t really like writing documentation and would prefer to just create “self-documenting code.” Indeed, various automation tools (e.g., Swagger or Javadoc) allow the generation of up-to-date documentation at any given moment in time. For fellow programmers, clear and well-structured code really may need little explanation.
But while quality code is the foundation of a successful documentation strategy, even the most pristine code won’t be transparent for non-development professionals. Documentation ensures that related business units have the resources they need to help the software product achieve its full value.
It’s also worth noting that unit tests play a big role in the technical documentation process. To save time, many developers prefer to avoid using them in the face of approaching deadlines. However, unit tests will be used as code specification, making support for further changes much easier in the long term.
Onboarding is a great example of the sort of practical operational need that great technical documentation is instrumental to supporting. Quality documentation ensures that new team members will need less-hand holding as they learn the lay of the land and minimizes the chances that a busy dev team will forget to mention a crucial detail.
Onboarding can also offer a great practical check on the quality of your current documentation. If a new team member reviews existing documentation and seems to be in the dark about crucial aspects of the project, there may be crucial gaps to address.
Software Development Documentation: End-User
End-user documentation takes the form of various sets of instructions, user manuals, and tutorials used to help new users successfully employ a software product.
Modern apps, web and mobile, are often designed specifically to notneed much end user documentation. And skillful, intuitive UI design certainly minimizes the need for formal manuals. But user uptake should be carefully considered as part of the overall development process: even a few simple instructions can go a long way. The more useful a software product is to it’s users, the more value it will generate. In a B2B or consumer-facing setting, some thoughtfully crafted instructions may dramatically cut down on the need for live support/training.
Software Development: Related Planning
This article is focused on documentation of the development process and software product. Notably, development documentation is just one aspect of the planning that goes into maximizing the value of a software product.
Providing for everything from marketing, to post-launch support, to product strategy is essential to a software product’s ultimate success.
For a deeper look at how careful planning can help de-risk software development, we recommend our blog here.
The Value of Fit-for-Purpose Documentation
There’s no hard science to project documentation, and practices should be kept flexible enough to be tailored to the project at hand: fit-for-purpose documentation will avoid both extraneous documentation work and the sort of poorly documented work that proves costly over the long-term.
In general, the larger and more complex a software product is, the more documentation it will require. Even in an Agile world, a big enterprise app with lots of complex integrations and secondary functionality may require substantial documentation. Similarly, a straightforward web app may only need an ultra-lean documentation approach.
When it comes to managing documentation during the project itself, team-size is another crucial variable.
For a smaller team that is frequently communicating about a project, check-ins over a platform like Slack may be the only process needed to keep team members informed of relevant documentation changes. In terms of tools, a smaller company building a relatively simple app may simply track projects in a Word Document or SharePoint.
For a larger team, or a team working for a larger enterprise with more extensive internal reporting processes, a more formalized approach to documentation changes and team communication may be necessary.
Distillery’s Careful But Practical Approach to Documentation
At Distillery, for example, we use JIRA-based project management and have experience with tools like Confluence (a wiki-based documentation tool with full JIRA integration). While these tools can make building and sharing documentation as easy and transparent as possible, they’re by no means necessary to building quality documentation—we also successfully deliver projects for clients who employ a much simpler approach to documentation.
Whatever the tools employed, it’s the project manager’s responsibility to track how each team member is documenting their part of the project, ensuring adequate knowledge is being recorded.
At Distillery, our goal is always to produce the amount of documentation needed to facilitate project goals: no more or less. We employ check-lists, for instance, to ensure that adequate documentation is produced across all areas of the project.
For any given area, like DevOps or architecture, the amount of documentation required by the project at hand may in fact be very limited. Overall, the goal isn’t to create demonstratively “comprehensive” documentation, but to avoid arbitrary-decision making: excessive and inadequate documentation both have real costs.
We’ve seen both sides of this cost-risk up close. In some cases, we’ve been engaged on projects where extensive documentation requirements took multiple weeks of dedicated time from a developer. We’ve also been called in to work on apps that other vendors left inadequately documented; it can take substantial amounts of time to understand the structure of the software and its environment, even if the code is quality.
When Distillery hands off a completed project to a client after a successful development cycle, we typically conduct a handover call to go over all completed and outstanding tasks. This initial knowledge transfer is a great time to answer questions and resolve any final issues. Documentation, meanwhile, helps ensure that this knowledge is institutionalized: preserved for the long term and paired with all the practical resources needed for future development work.
Learning More
We hope this article provides a useful framework for thinking about documentation for a development world increasingly defined by lean, Agile thinking.
Great documentation is just one piece of the best practices that go into building great, custom software products. If you’d like to learn more about Distillery’s approach, get in touch with us here.
We’d love to chat above building a development process tailored to the problems you’re trying to solve.