By: Akshita
November 22 2018

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 same, the process of building the software has become (more) Agile. 

an open file on top of two files


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

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

Agile’s emergence as a huge global movement extending beyond software is driven by the need to match up with the turbulent customer-driven marketplace. Agile enables organizations to master continuous change. It permits firms to flourish in a world that is increasingly volatile, uncertain, complex and ambiguous.

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

A graph on a white background
More than 50% of Agile developers are creating documentation

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. Which 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 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 in 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 a 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 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 piles. 

Possible Challenges around Agile Documentation

  1. No experience in writing: Programmers are not meant to write documentation. Lack of experience into 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 of information to share: Related to the first point, when writing in flow this can be a major blocker. Identifying and eliminating the 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 an 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 section, 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.

Conclusion 

Agile development methodologies are definitely the best you can get to induct 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.