Have Your Developers Have Been Lying to You?


Why Everyone Should Be Good at Documentation

The Agile Manifesto is quite clear about preferences when it comes to writing versus doing:

“We are uncovering better ways of developing software…through this work we have come to value…working software over comprehensive documentation.” But it’s a misconception to believe that within the Agile framework, or on Agile teams, there’s little to no room for documentation.

Developers, designers and project managers are eager to share horror stories about inefficient process and documentation. There are, after all, countless software and creative initiatives that have been crippled by a drawn out process surrounding abstract documentation, inefficient approval flows, and the dreaded freeze that comes from analysis paralysis. No wonder there’s an aversion to documentation.

“The misconception comes from the statement: ‘we have come to value software over documentation’”, says Shanly Suepaul, Senior Web Technologist & Certified Scrum Master at Myplanet. “But the true idea is, although we value all of those things we value development more…the point of calling it out was to say that we need to deliver value in our projects. We need to build things. Sometimes documentation is not valuable.”

As Shanly explains though, that is a very big, “sometimes”. It doesn’t mean that you should avoid documentation. As Shanly continues to explain:

“Now I’m on the most agile team I’ve ever been on, but at the same time it has the most comprehensive documentation. Multiple formats, multiple languages etc. Why? Because it’s valuable within our context.”

Value, Value, Value

The reality is that in any software project you’re dealing with thousands of details mixed together with tens of thousands of lines of code. And when you need to support executive visions, client expectations, user adoption and maintain team unity with key deliverables — most of which exist “under the hood” — documentation will rarely have zero value. It is important.

As Eric Lowe, an engineer at Oracle, once succinctly put it, “…the dominant factor between a successful project and an unsuccessful project reduces to the effective dissemination of key information.”

Whether you like it or not, and whether or not you believe in the TAGRI principle of software development (They Ain’t Gonna Read It), a significant amount of information must be communicated to different audiences and it must be communicated in a way that enables both immediate action and future reflection. Failure to see or accommodate for this puts your software (and potentially your client relationships) on shaky ground.

Formality Meets Flexibility

While documentation certainly injects formality into ideas, and some semblance of linear direction to sprawling specifications and ideas, the formality of a document is best achieved alongside flexibility. Nathalie Crosbie, Associate Director of Experience Design at Myplanet has seen the value of flexibility first hand:

“When we user tested our documentation with the developers, we realized how we had planned for them to use it wasn’t at all how they were actually using it or consuming it. So, thanks to consulting and collaborative design, we ended up doing a functional prototype with annotations. We created flexible documentation that matched their workflow.

“If we’re agile, we need to be agile to adapt this (document) to our user,” Nathalie continues. “When creating ‘documentation’, there are a few things to consider: flexibility for your audience and flexibility for what you (or your audience) actually consider to be ‘documentation’. For a designer, part of what documentation is, is guiding the development process. Obviously, that’s going to be different from what developers consider documentation.”

And clients, executives, sales reps and others may consider it to be something else entirely.

Understand Your Audience(s)

Each “user”, both internal and external, will have their own “use cases” for documentation. Not only must you appreciate those use cases as critical to the overall success of a project, but you must understand the tactical applications that arise in those scenarios.

Some people are looking to understand how something works prior to using it. Some people are looking to understand how something works long after adopting it. Some people are looking for instructions (e.g. Front-end developers), while others are looking for inspiration (e.g. QA Engineers, Sales Reps), and still others may be looking for progress and varying forms of proof of work (e.g. Clients). It’s a lot to think about.

As Nathalie explains: “Very often you’ve got the same document for (multiple) parties. In reality, you don’t need to do this. You shouldn’t do this. You have to tailor the documentation to the audience.”

A well-executed document satisfies all of your relevant communication use cases and delivers value to the targeted audience where needed.

“You have to explain how your software can be used,” Shanly says. “Documentation helps with this. Otherwise you assume risk or reputation damage if someone doesn’t understand what you’ve done and comes back to you with a problem.”

“It depends on the nature of the product,” he continues. “But if there’s a certain level of sophistication then you need to document it. If it helps to provide value, then you need to document it. Again it’s about creating things of value…If it’s something that your client expects, or values, then you should have it.”

Consider the Future

Documentation isn’t always easy, but it’s also not as complex and daunting as you may think — or as developers and designers may have led you to believe. Yes, there’s a difficult balance to be struck, as writing documentation requires using the same resources who are in charge of actually delivering product. But that being said, effective documentation absolutely enhances both process and product.

Think of all the broken telephone, remote employee communication delays, general forgetfulness and lack of clarity that can be corrected. Consider the contribution to client/customer/user goodwill, the higher usability rates, the repeat contracts and the reduction in technical support costs that happen from good documentation.

Especially in an Agile environment, where iteration is at the heart of the game, your product might not always always “speak for itself”. And at some point, someone in the future will need to understand why, how and what you did in the past.

“It’s a vital skill,” says Shanly. “It helps you communicate what you’re developing. It’s good for clients, users, and overall communication.”

Is good documentation more important than good product? No. But one thing is for sure: despite poor interpretations of what Agile might say, rarely does a good product exist without good documentation in front of it, behind it, or in it.

The key is creating the right type of documentation, the right volume of documentation, and delivering it at the right times during design and development cycles. At the end of the day, it’s all about creating value — which is exactly what we’re all trying to do.

Stay tuned for the full interview from Shanly & Nathalie where we’ll share more insights and key questions to help you create documentation.

Interested in working with us? We’re looking for great designers and developers → Apply Here ← No seriously, click and take a look at our open positions :)

Written by

Cahill Puil

Cahill Puil

Sign up for our newsletter