The long-term trend toward Agile project management 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, software 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, and documentation provides real long-term value.

Key Benefits of Quality Software Documentation

  • Expectations stay managed. Carefully documented project requirements help keep a project organized, on budget, and on time.
  • Needs are addressed. Technical documentation reflects the customer requirements, requests, needs, and specifics, allowing parties to manage arguments.
  • A forward focus is empowering. Quality documentation helps ensure that future development work can hit the ground running, ensuring your software product is a flexible long-term asset.
  • Teams operate with cohesion. Good documentation facilitates an optimal handoff from the development team to those actively managing the application (whether it’s consumer-facing, B2B, or internal).
  • Thorough planning ensures success. Selective, fit-for-purpose documentation preserves the flexibility of Agile development while ensuring changes stay tied to a plan that will meet the fulfillment of core requirements.

There’s no doubt Agile is pushing away from a rigid focus on exhaustively documenting every feature and coding decision. To reflect the dynamism of Agile development, modern documentation practices need to be adaptable on the fly. The ultimate need for quality documentation remains.

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

  1. Requirements
  2. Architecture/Design
  3. Technical
  4. 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 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 such fast-paced changes are 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 timely and within the 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 statement of work (SOW). As these changes take place and integrate into the project, software documentation can reflect exactly what function they serve.

For a time and materials contract, the project manager can focus on the practical impact of requirements changes, saying for instance, “We can add this feature, 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 behavior of the system. This documentation needs to not only track requirements, but how solutions are implemented.

Examples of architectural and design documentation include the following:

Wireframe Diagrams

These diagrams highlight your software’s functionality and user interface (UI). Through this documentation, you can paint a clearer picture of what type of user experience (UX) you are aiming to deliver through your software.

Wireframes are highly sought after due to their amalgamation of simplicity and detail. Even when you lose any lead developers or teams on your software, wireframes can help their successors have a firm grasp of your software’s core structure and goals.

User Interface Sketches

Whether your software is B2B or B2C, a point-and-click interface is the life and soul of its functionality. A UI sketch refers to the mock-up of your graphical user interface (GUI) that you want to create for your end users.

Through UI sketches in software documentation, development teams can outline the initial and final approach to their software’s GUI. This allows any onboarding developers to know what type of GUI they will be working with, which helps set expectations through visual cues.

Topology Descriptions

Topology descriptions allow you to map your software’s functionality and connectivity to other applications. This also lets you highlight the accessibility of your software through multiple devices and networks, enabling your development team to oversee your application’s connectivity requirements.

Topology descriptions are helpful in any software development approach. But they are particularly essential in enterprise software, where you want to outline your application’s connectivity to other networks in your organization. This makes it an important aspect to remember while drafting your documentation.

DevOps Information

Agile development acquaints your software with cross-functional and overlapping engineering teams. By contrast, DevOps focuses on implementing collaboration between the development and operational teams. Combining both streamlines software development and delivery, staying in line with organizational goals.

Software Development Documentation: Technical

Technical documentation captures program code. Such documentation includes the following:

  • API descriptions: helpful information for developers to use your API, connecting their applications to your software.
  • Lists of environment variables: environment variables that tie your software to certain processes.
  • ReadMe files: software documentation that helps your developers and end-users learn more about the functionalities and operations of your application.

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 specifications, making long-term support for further changes much easier.

Onboarding is a great example of the sort of practical operational need that great technical documentation is instrumental in supporting. Quality documentation ensures that new team members will need less hand-holding as they learn the lay of the land and minimize 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 software documentation. If a new team member reviews existing documentation and seems 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 to help new users successfully employ a software product.

Modern apps, web and mobile, do not often need 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 its 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.

Your end-user documentation does not have to be a tedious read. By creating helpful yet engaging content that is deployed with your software, you can ensure that your end-users have all the information they need to resolve common hurdles on their own. This adds to their user experience, while helping you focus on the consistent refinement of your software instead of resolving avoidable complaints all by yourself.

Following modern approaches, you can host this documentation on your own website. This cloud-based hosting of documentation keeps your end-users from being laden with multiple files when using your software, while also allowing you to quickly integrate any updates into your software documentation as they occur.

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 and 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.

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 software 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 checklists, 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 in 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. Software 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 about building a development process tailored to the problems you’re trying to solve.