This article is the third part of a series on: The end of the agile world hasn’t come. Read part 2 here.

Alright, let’s look at the second fundamental value of the agile manifesto:

[…] We value Working software over comprehensive documentation

Honestly, I even hesitated to write a dedicated article to argue about this one.

• Does anyone deny that they’d rather use a product than read a user manual?
• Who has never directly started using his new phone without even daring to look at the guide?
• Who has a few hours to waste nowadays, before they can actually get stuff done?

Of course, documentation should always be there as a backup. Again, they’re here to help where humans fail.

But let’s try to dissect this value. Of course, you can view documentation as a support to internal users (the development team), and as a support to external users (end users). I’ll write it more from the second perspective, but I’d say that my standpoints can be just as valid for both.

To me it means:

1. The end-user experience should enable intuitive getting started/The architecture should make it intuitive for a new developer to join the team (Thank you frameworks!)
2. No major bug should alter or interrupt this user experience (yes, there’s no bug-free software in our world)/The technical debt should be as limited as possible
3. There should be no “FAQ” section on your website/cookbooks in you (limited) dev doc.
4. The purpose and requirements of the software you develop should be crystal clear to any user (true both for internal and external purposes)
5. The support team should be constituted of the people who created the product

Where the first 2 points are pretty straight forward, even if there’s unfortunately quite often some opinion fights in a team regarding it, Let’s look at the last three.

There should be no FAQ on your website

Why? Because a frequently asked question, getting an answer in writing is obviously a use case which you were not able to manage according to point 1!

Period.

Purpose and requirements should be crystal clear

I already wrote a bit about finding the right user problem. Not only it must be clear for you, what you are trying to solve, but it also must be clear for the user.

How many times have I heard: “I doesn’t work for me”, while the user was trying to do something with a product that wasn’t serving that purpose? It’s easy to just say “Well, that guy is stupid”. I say: the creator of that product is stupid. If he can’t make clear enough to somebody what his product is supposed to do, and not to do, then he should immediately stop working on technology, and start wondering about what he has created.

Now of course, the corollary is that you should be loyal to your value proposition.

Next is to make sure that the user will never start any configuration or usage before knowing for sure that the product can actually work in his environment. This may seems like twisting a little the “working software” value. Indeed, you’d expect that while trying to reach this value, your software should be working in any environment. And to a certain extent, you’d be right. Now, today, we all face it, the software world is so branched out that it is virtually impossible to package solutions for all of them. Think of OS distributions, but also browsers, third party services, etc…

And even if here as well, writing the requirements in a doc is something mandatory, it’s far from being the only option:

• when possible, you should detect the users environment before he does anything and let him know if he can go further
• else, when your product requires configuration, the very first step you be for him to select the environment on which the configuration will be made, and that should condition any other interaction.
• the purpose should include a clear scope of requirements
• and mentioning the first agile value “individuals and interactions”: if you have a sales team, make sure they never can unintentionally sell a product without knowing that the client doesn’t meet the proper requirements. Communication, baby.

Support team = designers + devs

This may be one of the toughest point to adopt. Because no developer nor designer will ever accept from day one this “unattractive, low value-add” task. They’re cleverer than that.

Note: designers to me are UX designers, UI designers, product managers, product owners, and whoever else might be involved in thinking on how the product should look like/do.

Well if they do accept, you’re lucky, and on the way to the greatest support you can imagine.

Who can better answer questions or solve problems than the people who built the stuff? And more importantly, what lesson is better for a designer/developer than to be confronted to the hard fact and user reality? Exit opinions, we now know how users feel when they face our buggy product! And that’s the shortest loop to getting working software.

Bonus: End-users will always feel important when knowing they they directly talked to the guys who built the stuff. They will never have to face a person reading trying to figure out which keywords from the user’s inquiry best match the paper list of FAQs, and totally miss the point. And satisfaction ensues.

Working software over comprehensive documentation is key and an obvious value. And as we’ve seen, it’s more than just developing a bug-free product. It involves everyone in the organization.

Read part 4: Customer collaboration over contract negociation.

Featured image by Dustin Gaffke