Strategizing Agile Documentation: Myths, Practices & Goals

If it wasn’t documented it didn’t happen. 

While the world is more interested in the end product focussing on the specifications and intricacies, the ‘process’ has become less stimulating to them.

Behind the scenes, the process is what steals the thunder. And a more important part of the process is documentation. Under the traditional software development system, documentation starts and ends with the project. 

While the purpose of documentation remains the same, the process of building the software has become (more) Agile. 

When the development process keeps changing without following a set plan, how much does it affect the documentation? What are the best practices to follow when documenting an Agile product?

And most importantly should documentation be even part of a project where big up-front planning or strategies are not even defined?

Let’s explore.  

What are Agile Practices? 

Advocating adaptive planning, evolutionary development, and continuous integration, Agile software development methodology is about the rapid deployment of changes into the software. The approach to software development, in this, is around accommodating requirements and collaborative efforts giving birth to the product which meets the new customer needs as well. 

The emphasis on “responding to change” over “following a plan” might confuse you for a minute. It is capable of giving the impression that their is no planning at all. However, it is more like adaptive planning. Agile enables firms to flourish newer ideas and strategies given the volatile and ambiguous nature of the marketplace. 

Doing away with the rigid structure, Agile implements a shorter plan with a scope of iterations that can replace without wasting efforts on planning elaborately. 

Some of its distinct features involve continuous feedback, sprint planning, and shorter and quicker release cycles ensuring more transparency into the project management.  

Types of Documentation

With every developer and project being different, there are different types of documentation that can be maintained by the teams. Software documentation, in particular, can be categorized as:

Product documentation

It contains information about the product that is under development and it includes instructions that have to be executed. With various tasks at hand, it can be further divided into:

System Documentation: Describing the system itself, this document has data related to design, architecture descriptions, program source code, and help models. 

User documentation: This covers tutorials, user guides, troubleshooting manuals, installation, and reference manuals for the end-users of the product. 

Process documentation

Documents that are required during the development and maintenance stage are under the process documentation. For example project plans, schedules, reports, standard tests, MoMs, and similar.

Maintenance documentation

Often the plans are flexible in Agile and can need constant maintenance with detailed reports that combat discrepancies. This style of documentation is purposeful for addressing the needs of audit or maintenance teams.

Discussion and documentation

The constant flow of discussion among the teams also plays a pivotal role in refining the processes and thus, the documentation. With every new idea that comes to the court, the document becomes concise and gets nearer to the goal.

What is Agile Project Documentation?

Agile documentation as a term or practice doesn’t exist. It is loosely used to infer the active documentation done while the software product is being created using Agile practices. 

Although it is internal documentation, there is no defined standard to make it. 

In a traditional project setup (the “Waterfall”), documentation is as important as the end product, with many times team members waiting for the documentation to finish before making exit in a project. 

“Documentation should never be an end-in-itself and any documentation should provide value to someone in some way.”

Hustling in a fast-paced environment, Agile calls for making some important decisions in documentation such as figuring out: 

1. The kind of documentation to be produced 
2. Who will gain the most out of it
3. The value it would provide
4. How that value can be produced most efficiently and effectively without creating any unnecessary overhead. 

The above-mentioned rules encompass to all forms of documentation including:

1. Internal documentation used only within the project team
2. External documentation used by people such as stakeholders outside of the project team
3. Any other documentation that is used for ongoing training and support of the project

These factors and their approach is completely in contrast with the documentation approach followed in a traditional environment, where a lot of documentation may be mandatory as a required deliverable to satisfy process requirements.

Since Agile is based on a more intelligent and faster process to software development and delivery process, documentation in Agile is done by the programmers. 

“But remember programmers don’t write documentation” 

A disputed proponent of Agile methodology how different is Agile documentation from the traditional?

User Intended Documentation vs Internal Documentation

User documentation as the word suggests is directly related to and made for the end-user (or customer). A know-how of the product, it tells people how to use it. It can be a user manual, online help or a set of FAQs. They are prepared by marketing and sales executives. 

Internal documentation or developer documentation is not part of the end product and limited people have access to it. It is related to how or why the product was built, the way it was. It broadly covers technical specifications such as codes and sequence diagrams, and so on. They are made by architects, business analysts or developers and consumed by their counterparts in the present or future. 

Breaking the Myth. Agile Documentation is Important 

The purpose of every product is to provide the maximum amount of usability to its user. Always. 

No second thoughts on it. 

As a developer, your code is self-documenting to you (since you made it), but it can be a nightmare for others to understand the complexity of it while making changes in your absence. Among all the other myths around agile development methodology, there is one and most pertinent of all, around the documentation. 

“But there is no documentation in Agile”.

Agilists are in fact writing documentation. DDJ's 2008 Modeling and Documentation survey found that agile teams were just as likely as traditional teams to write deliverable documentation such as user manuals, operations documentation, and so on. 

The hastily scrawled post-its provide no value to those working to understand the software later. This is actually a hard problem (no document).

The purpose of Agile documentation is to keep the product development process transparent setting out the specification, codes, and changes. 

Since Agile methodology assists teams in responding to the unpredictability of constructing software and adapting to the upcoming needs as per the demands, documentation provides a lot of help in keeping the software robust. 

Documenting the process and codes add to the life of your software.

In case you have produced documentation check if it is enough for your teammates? Does it provide value to the one who has to maintain it a couple of years from now? Is it sufficient for an operations engineer trying to fix things at midnight? 

Agile is intended to be adaptive. This means as soon as a change is made, it needs to be documented. 

(In Agile methodology) development can seldom go back to an earlier stage for modifications, functional designs and documentation (of codes) becomes all the more important.

But what kind of documentation should be done? 

Scott Ambler, a Canadian software developer, and author, in his essay “Just Barely Good Enough Models and Documents: An Agile Core Practice” states that agile documentation should be "just barely good enough" and that too much or comprehensive documentation would usually cause waste. Since developers rarely trust detailed documentation because it's usually out of sync with the code, too little documentation may also cause problems for maintenance, communication, learning and knowledge sharing.

Your team's primary goal is always to develop software, but the next aim is to not waste those efforts. Of course, building niche quality working software which meets the needs of your stakeholders is important, but ensuring that the people who come after you can maintain and enhance it, operate it, and support it is also important.

Benefits of Agile Documentation

With a lot of mediums, different purposes for various stakeholders and the style of writing, documentation can be overwhelming. 

Covering the benefits of how developers can use these to communicate while complementing with codes, scripts, and tests, here’s how Agile documentation can benefit:

1. Ensures everyone is on the same scale
   
   Since everyone works at a different pace and has a different level of understanding, frequent sprints can fail the memory of some of those working on the project, let alone those maintaining later (who won’t be aware of the process). 
   
   It is therefore important to ensure everyone is on the same scale. 
    
2. Makes the software robust
   
   Short-sightedness can astray developers to believe that little or no documentation on the codes is enough. Things that look trivial, might turn up to be important with others. 
   
   It is these little things that ensure things are understood and also help evaluate if the implementation makes sense, and to uncover accidental complexity. 
   
   Imagine the maintainer can’t understand why the problem is tough to crack because nobody understands where the problem is in the first place. 
   
   Keeping the document up-to-date ensures bugs and issues are easy to track. 
    
3. Creates a better spirit among the team members
   
   When things are well documented and the procedures and details laid out properly, it creates a better understanding of the project. A transparent process will create better empathy among the team members around the responsibilities they share. 
   
   Empathy helps create a better understanding of the challenges as well. And working on a software sans any guidance that can be nerve-wracking. 
   
   Creating an environment where people feel guided and safe when changing the software must always be welcome. This is particularly helpful when onboarding and troubleshooting, like “readme” files, or checklists for things that are not automated yet. 

Bonus tip: Ensure every piece adds value to the organization not just in the form of document files. 

Possible Challenges around Agile Documentation

1. No experience in writing: Programmers are not meant to write documentation. Lack of experience in writing can turn out to be one of the challenges. Developers are good in the technical part, but they are way too often helpless when it comes to describing it. A possible solution to this is to hire someone with a technical background. 
    
2. Too much information to share: Related to the first point, when writing inflow this can be a major blocker. Identifying and eliminating redundant information is tough, especially if it is written by you. Make sure that only crisp and relevant information is part of the documentation. 
    
3. Started too soon: Once written, rewriting is only wasting the efforts. Practicing some patience while writing can be helpful, especially when the purpose is to write minimum things giving maximum output. 
    
4. Scattered data: Keeping the diversity of the team in mind, documentation notes must be kept in one place and should be accessible and transparent. 
   
   In order to avoid a clear mess (oxymoron, I know), ensure the paper/e-docs are combined in one place at regular intervals. All employees should look at the compilation from time to time. It will help them remember the main objective. In addition, it will keep them informed about all the renovations.

Best Practices to Write Agile Documentation 

The documentation procedure is divided here into two parts to get a better understanding of the before and after writing the documentation. 

• Understand the Scope of Document before Diving
   
  • Document with a Purpose 
    
    The foremost thing to take care of when creating a document is to identify the purpose. If the purpose requires a document with a clear, important, and immediate goal of your overall project efforts, only then create one. The purpose can always be short or long term involving other stakeholders than the developers. 
     
  • Identify the Needs of the Documentation 
    
    Once the purpose is defined, find the stakeholders involved. You would want to work closely with the potential audience of that document, to improve its usability. 
    
    Identify what they believe in and what they require, and then plan accordingly to reduce the information gap. 
    
    By understanding the needs of your customers you will be able to deliver succinct and sufficient documentation while producing eminent value.

• Writing Effective Documentation

  • Agile is Not Static

    The majority of the information captured in traditional specification documents, such as requirements specification, architecture specifications, or design specifications, can be captured as "executable specifications". 

    When you take Agile documentation they need to be effectively written with detailed specifications and changes starting from development to the deployment phase. They are not static. 

  • Keep it Crisp and Precise

    The Agile strategy is to eschew from the unnecessary steps with only the most relevant things being followed and documented. Once the vision of the document is created, it is easy to avoid redundant information. 

    Prefer executable specifications over the theoretical ideas. Try to minimize the overlapping of information. 

    Document your decisions only if there are alternatives and you need a reminder of what was behind those decisions. Since a certain procedure might repeat, control the urge to document it completely. 

    Write for the situation at hand which is just good enough to fulfill the overall purpose. 

  • Keep the Doc Updated, Don’t Wait

    The methodology focuses on mastering continuous change. This requires the need to update the documents as frequently as the real-time changes in the software to ensure maintaining high-quality working software for later, too. 

    Don’t jump up to write, too soon. Wait until the decision is implemented and there’s no going back whilst you put it on paper. 

    Ensure the information is stabilized and reliable while you economize the cost, time and effort, spent on redoing your documents.

  • Write Less, Write Best

    Let the people who need to use the document later decide the content. 

    Since Agile teams are often diverse in nature, information overlap is a possible reality. Instead of breaking down each team’s part into pages and sections, club them into a day’s activity. 

    This would allow the table of contents to be non-repetitive, coming out both as a support and information guide. The advantage of this is that information is defined in one place only, reducing any chances of overlap.

Think of your documentation as a requirement

In an ideal case scenario, documentation should be created throughout the entire software development lifecycle. Writing documentation is as important as the process of the product. Real-time feedback adds to its actual value. 

In other words, write little, get feedback, act on it, and iterate.

Achieving 3 Goals with Agile

A Common Ground

A lot of times a simple bug can become the cause of discord and opinions that collide. Or when a change is needed to be done, the teams cannot fathom the right path to take due to differences in their stance. Therefore, a common ground of understanding based on documentation becomes important for everyone involved in the project. Any phase of change should have an elaborate system of rules and logic. With Agile documentation, you achieve a base for fixing such loopholes.  

Empathy between Developers and Non-developers

It is common knowledge that the rifts between the decision-makers and developers are difficult to solve. Often the lack of knowledge among the project managers gives the developers a hard time.  

In Duretti Hirpa’s article about "Empathy Driven Development", she describes “empathetic codebase” as a notion of creating a codebase with an advantage of “any tool that will provide context”, including documentation.

The whole act of creating documentation shows a sense of empathy towards the teammates and builds an environment of a safe and guarded workplace. 

Make Informed Decisions

With all the emphasis on documentation, how does one manages it for the future? 

Do not be afraid to discard the documentation that seems to be unnecessary. Agile is all about efficiency and keeping the processes simple. Considering the value of particular documentation via collaborative ownership, you can discern its significance and share the responsibility of updating it. This activity helps you achieve the goal of making decisions that are in the best of interest of the team as a whole.  

Conclusion 

Agile development methodologies are definitely the best you can get to induct the best industry practices for software development.

Explore more about Agile processes and understand if it is the right fit for your software development needs, contact us at [email protected].

The goal of any documentation is to provide a complete, unambiguous result and a record of the changes incorporated including the final results. 

Documentation becomes more important when working on an Agile process.