Documenting the Agile Design Phase

What Is the Design Phase?

The design phase is where the building of a product actually happens. It comes after the requirements phase and is typically the longest part of the Agile cycle and requires effective work management and close collaboration, not only between members of the software engineering team, but also with stakeholders outside of the team.

The design phase allows the team to explore multiple solutions, then select and refine the best one based on feedback from peers and other stakeholders. This could include those within the organization, but also potentially users or customers.

In many cases, the design phase for Agile teams is iterative, meaning it follows a pattern of developing code and then identifying improvements to be made for the next round of review until it is ready for deployment.

The first sprint when starting a new project might only result in bare minimum functionality — but there will be plenty of future sprints to expand on it and develop the product further.

Why Is Documenting the Design Phase Important?

Even though working software is the ultimate goal of the Agile methodology, it’s also important to establish a foundation for quicker and more efficient work in future efforts. Documentation fills that need by providing an accessible resource with information about what’s already been done and why it was done that way.

But why not wait until the product is all done to build documentation; wouldn’t that be a better use of time? In an iterative Agile framework, progress is incremental and your product or feature may never be “done”. Building, testing, and monitoring your product is continuous, so to align with that approach, your documentation strategy should be continuous as well.

Therefore, it’s helpful to build documentation throughout the development process instead of before or after. This also saves your team time by allowing them to incorporate documentation-building into their daily routine incrementally rather than having to reserve larger amounts of time for it later.

How to Document the Design Phase

So how do you create a balance between building documentation that sets your team up for future success, and avoiding wasting time by documenting unnecessary information?

A general rule is to keep your documentation simple and create only as much as necessary. That means being selective about what is worth recording. Here are our guidelines on what to document during the design phase and how.  

Logical Aspects

The logical aspects of a system are the details that describe how information flows through it. It’s a summary of all the activities required for a process to function.

These are important to document during the design phase because it’s easier to recall and communicate a system’s logical aspects while they’re still fresh in your mind. It’ll be faster to get it done early, and it can even form the foundation of customer-facing product documentation in some cases.

Data flow diagrams are a common way to document the logical aspects of a system. Some UML diagram types such as activity diagrams serve a similar purpose and are simple enough to bridge the gap between technical and non-technical audiences.

Logical aspects also include any dependencies and troubleshooting guidelines for your system that will help guide whoever is responsible for its maintenance.

To learn more about important diagram types that help you communicate the logical aspects of a system, check out our guide to the essential application architecture diagrams.

Physical Aspects

The physical aspects of a system are the devices, databases, and people that carry out the activities that enable the processes described in your documentation of the system’s logical aspects.

Data flow diagrams, which are a common way to communicate the logical aspects of a system, can also be used to visualize its physical aspects. Entity-relationship diagrams may also be helpful for documenting the physical aspects of a system when working with complex databases.

If your system is cloud-based, does that still count as “physical” architecture? Even if it might not be physical in the strictest sense of the word, if your system uses Cloud-based servers that act like physical servers, they can still be considered part of the system’s physical aspects.

Rationale

When your team makes decisions about the physical and logical aspects of the system that affect the way it’s built and the way it will be expanded and maintained in the future, it is absolutely crucial to keep documentation of why that decision was made and what other alternatives were considered.

Why? Because this can prevent miscommunications and repetitive work in the future. If you have clear documentation of why you made the decisions that you did, you can refer to this documentation when future issues arise.

To learn more about why decision-making documentation is important, check out our blog on the most important types of documentation for software development teams.

Start Building Effective Software Documentation Today

Want to learn more about building effective documentation through the entire development life cycle, not just the design phase? Make sure to download our ebook, Building Software Documentation Your Team Will Actually Use. In this ebook, we go into more detail on why documentation matters and how to build it in a way that benefits your team but doesn’t take up all of your time.

In order to build the data flow diagrams (among other types) to visualize the physical and logical architecture of your system, as well as follow many of the other best practices laid out in the ebook, you’ll need a diagramming tool that allows you to build visuals alongside your documentation.

Gliffy allows you to diagram directly in Confluence, so you can save time while building your Agile documentation. Add it to your Confluence space today — it’s free to try for 30 days:

TRY GLIFFY FREE