Blog by LLM
Documentation in the Age of Agile

From the Wikipedia article on Software Documentation:

Documentation and agile development controversy

"The resistance to documentation among developers is well known and needs no emphasis." This situation is particularly prevalent in agile software development because these methodologies try to avoid any unnecessary activities that do not directly bring value. Specifically, the Agile Manifesto advocates valuing "working software over comprehensive documentation", which could be interpreted cynically as "We want to spend all our time coding. Remember, real programmers don't write documentation."

A survey among software engineering experts revealed, however, that documentation is by no means considered unnecessary in agile development. Yet it is acknowledged that there are motivational problems in development, and that documentation methods tailored to agile development (e.g. through Reputation systems and Gamification) may be needed.

For the non-agile-informed...

The concept of "working software over comprehensive documentation" seems to imply the non-necessity of end-user documentation.  If your software is adequately intuitive, there is no need for a user manual or support website.  

When interpreted in this manner, there are two points in this concept that are short-sighted.

First of all, even working with very intuitive software, there are still times when a user will have questions.  This might be due to a load of features that takes some digging through, so the feature is overlooked.  It may be simply because the software does not offer the feature, and users are stunned that the software company would not include what they feel is a critical feature.

Secondly, end-user documentation is not the only kind of documentation.  Even if your software works perfectly, there needs to be information on its design, how it interacts with other products (e.g., web services), and the vision for its future.  There may be compliance documentation required by regulatory agencies.

The sheer nature of software design and development begs the need for adequate documentation.  Comprehensive documentation is critical - to avoid potholes down the road, and to avoid newbies making mistakes their predecessors made and learned to avoid.  As they say, those who do not know history are doomed to repeat it.

Yes, we are in the sound bite century.  Tweet-length attention spans.  One line (or one word) texts instead of emails.  Yes, this is modern popular culture.

But we don't want our surgeons skimming over their medical texts before operating on us.  We want them to have read all the books, taken the tests, and passed with flying colors.

For the agile-informed...

Likewise, smart software companies don't want their newly-hired developers to not make the effort to learn all they can about the company's software, systems, tools, and design decisions (recent past, present and future).  Otherwise, the newbies are just shooting from the hip on the day-to-day, filled with questions ("why did they do it this way?") due to not knowing the history, and stabbing in the dark at how to work with the tools and repositories placed before them.

Taking the time initially, and on an ongoing basis, to consume comprehensive documentation - whether through video training or simply reading -  can save a boatload of time and mistakes down the road.  

I always write documentation with the goal of preemptively answering questions that users (end-users or developers) will ask.  I will always include screenshots of even mundane steps in a procedure because it reduces confusion, and ultimately, support calls/tickets and the time and money it takes to handle that. 

The Agile Manifesto is directed primarily at development and developers, of course.  The comment "real programmers don't write documentation" says to me that technical writers (and/or tools or other methods) are needed even more in an agile shop.   While developers are writing code (or after a sprint is completed), they can describe their code and design decisions to a tech writer, and get assistance documenting their work.  Or use a tool to assist. 

There are quality tools out there these days that help developers document code.  Using these tools and/or a tech writer makes documentation easier to create.

More Blog Posts by LLM

All content copyright Laura L. Martin.  All rights reserved.

This content may not be copied or reproduced without prior written permission and credit to Laura L. Martin.