Refiguring The Primary Measure of Progress

pencilIn Agile Software Development,

“working software is the primary measure of progress” and the manifesto values “working software over comprehensive documentation.”  That is all well and good, but as a writer, I often pause on that one word – comprehensive. I take a moment there and wonder who determines what comprehensive means, and whether sometimes we leave the customer, and the customer’s needs, in the dust when we use that word.


Before every developer everywhere has a head explosion, I think we can all agree that expansive documentation is silly and frivolous. So maybe I would swap out comprehensive for expansive. Perhaps I’d have chosen “frivolous documentation,” or “needless documentation.” I’m just not sure I would have chosen the word comprehensive. I get what the manifesto is going for. I do. I want to create lean, usable doc every time. I don’t want to give more than is needed. I want to respond to change fast. My goal is accurate, deliverable doc that addresses stakeholder needs. I suppose I would like to think that, by definition then, my doc is complete, or…comprehensive…in that it includes everything a customer needs. But I agree that I don’t want it to include anything more. I just want to avoid coming up short.

What if I rewrote the twelve principles from a doc-centric focus? Would they work just as well?

  1. My highest priority is to satisfy the customer through early and continuous delivery of valuable documentation.
  2. Welcome changing requirements, even late in documentation. Agile processes harness edits for the customer’s competitive advantage.
  3. Deliver accurate documentation frequently, from a couple of weeks to a couple of months, with a preference for the shorter timescale.
  4. Business people, developers, and writers must work together daily throughout the project.
  5. Write documentation around motivated individuals. Give them the environment and support they need and trust them to get the doc written.
  6. The most efficient and effective method of conveying information to and within a writing team is face-to-face conversation.
  7. Clear, concise documentation is the primary measure of progress.
  8. Agile processes promote sustainable writing. All team members should be able to maintain a constant pace indefinitely.
  9. Continuous attention to linguistic excellence and good design enhances agility.
  10. Simplicity – the art of maximizing the amount of writing not done or words not written – is essential.
  11. The best architectures, sites, and manuals emerge from self-organizing teams.
  12. At regular intervals, the team reflects on how to create more effective doc and then adjusts accordingly.

Okay, so some of this is silly, and I just wasted twelve lines by playing it out all the way to the end, but it was for good reason. Continuous deployment can happen not just with techmanualdeveloping software, but in the embracing of documentation as part of that software, but instead it is often “kicked to the curb” by many teams as a misinterpretation of that one element of the original manifesto.



It’s not that documentation should be cast aside; it’s that comprehensive documentation is being misunderstood as frivolous or extraneous documentation.

I did not realize that this was a pernicious issue quite so much until I was giving a workshop to a small class of new developers from across my company, hailing from a variety of offices, and they looked at me funny when I described some of how my team does doc (we are pretty good at the whole agile thing, but sometimes we regress into “mini-waterfalls” and I hate them). One of the young devs was astonished that I manage to get my developers to hand over documentation early in the process so that I have it in a draft state, while the code is still being written, not after the code is all in place. It’s a struggle, I’ll admit, but when I this happens, the result is a joyous celebration of shared workload and well-written doc. We can collaborate, change, shift and learn. And the sprint goes more smoothly with only minor changes at the end, not a doc dump in week 4.

To teams who are not doing this: cut it out with the waterfall, guys. Doc is essential, and your users need it. Otherwise, they are calling support and costing your company thousands with every call. Change your practice and build your doc while you build your product.

You might be asking, “How can you possibly write the doc when you haven’t written the code?”

You are not the first person to ask this, trust me. The answer is pretty simple. A long, long time ago, you couldn’t. Or, at least it wasn’t wise to, because it was a redoubling of work. When writers put their stuff into pdfs or word documents, and then had to make major changes, it meant a bunch of editing and rewriting things. Therefore, developers got in the habit of writing all of the code, then examining the processes and hunkering down to crank out the doc. Fair enough. Now, though, we developed wiki spaces and collaborative tech writing tools that now allow inline editing and let developers look at the cool formatting and linking that tech writers have done with our work.

And – before the code even gets written, there is a design plan in place, and usually a design document to go with it. There are code specifications, right? You can have a nice chat with your friendly tech writer and go over this, either through a face-to-face (see Agile point #6) or via any of the vast number of other tools designed to communicate with your team. Before a developer starts coding, there is a project plan – share that plan. Once the general information has stabilized, it’s okay to let the writer have at it. The benefit is that the writer is having her way with the general plan while the developer is coding away. At the end of both work days, the writer and developer have each created something. In a typically short iteration, it is unlikely that the coding will change significantly, so the two can touch base frequently to mark changes (See Agile point #4).

Are there risks to this process? Of course, just like there are with waterfall. Remember that with waterfall, there were a fair amount of times that programming crept right up to the deadline and documentation was hastily delivered and could therefore be sloppy and lacking. And in this method, it is far easier to tell you about writing documentation continuously than it is to actually do it. It takes time, it takes effort, and it takes dedication – because the primary risk for doc is the same as it is for the software: that the customer’s need will change midstream. That problem was (more or less) solved by short iterations in development, and it is (more or less) solved the same way in documentation.mario

The benefit is this – by writing the doc alongside the development, you can be sure that you deliver the doc in sync with the product. You’ll never sent the product out the door with insufficient instruction, and you will never cost your company thousands of dollars in support calls because your customers don’t understand how the product works or how to migrate it. But deliver a product without comprehensive – yes, I’m back to that word – deliver it without a complete doc set, and you may regret it. Trial and error is okay if you want to see how fast Mario can get his Kart down the hill in order to beat Luigi and save the princess, but do you really want to rely on that when the client is a multi-million dollar bank?

I’ve been teaching writing and writing processes for a very long time, and believe me, the action of draft, revise, revise, revise is not new.

It’s just Agile.


Want The Very Best in UX? Hire a Writer

Saying that all technical systems, website creation teams, and indeed software development companies can benefit from a User Experience Designer is like saying that all human bodies can benefit from water. It’s a simple assertion. We all know it, and yet some development groups assume that they know what is best for their customers, or worse yet, they assume their customers know what they want.
What they (the companies, not the customers) do not realize is that the easiest way to enhance the user experience is to hire a good writer. UX design encompasses art, yes, but it must essentially encompass understanding. This seems intuitive, and yet when we look to engage a User Experience professional we do not always assume that he or she is a talented writer.
How do I know this? Well, I used to teach within a professional seminar for the MA in Human-Computer Interaction at a highly-respected university where they were grooming tomorrow’s User Interaction Designers before I took this primo job writing amazing documentation for this crazy-talented company cranking out top-notch software. Surprisingly, though, when I landed here, we did not have a UX guru on our team. I was a bit taken aback that we didn’t have someone like that on the job, but I figured I was new, so I didn’t make waves. Besides, I knew all on my own that really, if there is no art involved, you don’t need interactiondesign, you need interaction writing. So UX talent is not required – a trusted relationship with your writing team is.
I’m not saying that a writer can replace a designer – that’s just bad math. A company that wants to succeed in designing good software, web interface, and more, needs to hire the people who have expertise in software development and web design. After all, writers can’t develop code! But what writers can do is parse the meanings of things. We have the highly developed talent for taking complex ideas of language and inference, metaphor and symbolism, and making meaning from them. And we can tell you when it just doesn’t work. And many of today’s writing programs require classes like Document Design, Communication Design, Visual Communication, and more – things that are akin to how users interact with the ways we are trying to reach them.

Writers understand story. We tell stories. And in agile development, what do we call the very things that are on the table for development? Yes! Stories! In scrum meeting after scrum meeting, we task out stories for development, and the scrum master even relies on scenarios to help the team imagine how those jobs will be completed. It is proven in release after release that picturing how a certain element of the product will be used, valued, and consumed by the customer or end-user is a useful tool to the development team. Storytelling allows agile methodology to work, from start to finish. Good writers understand tension and pain, so writing a story or scenario helps to flesh out the documentation that will guide users through installation and troubleshooting. Writers are instrumental in sensing where and when the struggle points will hit for the team long before the software is released for general audiences.
Writers “get” emotion. We deal with it all the time in storytelling. Put a writer in the room in every scrum meeting and just watch how a talented one can help diffuse tense moments over hours invested in an idea that didn’t pan out. It isn’t foolproof, but a writer is also a good catalyst for humor, empathy, kindness and redirection in the heat of the moment. Many writers have a genuine interest in the investment of people, and writers can often help find a silver lining – if there is one to be found – and can redirect the energy. The User Experience is not always found on the outside of the room. Part of the experience is getting the product out the door without trauma.

traumaThe common argument against having a UX person on the team is cost, so often companies toss out the notion as a line-item veto in budget discussions. If there is a place for everyone at the table, that is fantastic, but in the current economy, often we are asked to develop multiple, portable talents. Those who can carry talents across the table are asked to do so. And they should.
The next time you are wondering how your customer might perceive something, I’d ask you to look across the table at your gifted technical writer, your talented copy editor, your incredible documentation specialist, and say, “How does this read to you? What do you think our customers will say? How does this look? What story does it tell?”
You might just be pleased with the answer. You may have found a user…with experience.