I attended the TCCamp conference…er…unconference last weekend. Short review: I enjoyed it (again!). I attended Tom Johnson’s great intro to API documentation, I talked to some interesting people, and I got some practical advice during the three discussion sessions.
And I won an iPad Air 2 (thanks to XMetaL/JustSystems), which is FREAKIN’ AWESOME.
But I want to focus on one topic that came up during the “Technical Communication in Agile” discussion: the concept of Minimum Viable Documentation.
Docs and Agile
I’ll start with the summary of this session that was presented at the end of the day: “Creating docs in Agile is hard.” There a lot of things we can do to make sure we create great content in an Agile development environment, but they involve a lot of work: attending scrum meetings, making sure that docs tasks are associated with feature tasks, creating accurate time estimates for the documentation tasks, etc.
I was a bit stunned. This is utterly heretical and wrong and against all that is right and proper. Good documentation has screenshots. Customers love screenshots, they help orient the reader to the UI. I reject Chuck’s argument that there’s no need for them in online help because the reader can just look at the user interface (this doesn’t apply if they aren’t looking at the same screen, and even if they are, screenshots can show the reader exactly what to look for).
But then I realized…
That bone-deep revulsion to this idea lasted for a minute or two. Because Chuck explained that in the extremely tight schedule of an Agile process, the UI changes so quickly that it’s impossible to keep up. He needs to focus on the written content, and can’t spend time taking and retaking screenshots.
I’m still not entirely comfortable with this. I think the lack of screenshots reduces the value of the documentation.
But then I remembered the idea of Minimum Viable Documentation. I picked this up from Matthew Lyon’s presentation at Write the Docs, and it’s stuck with me. (Andrew Spittle wrote a great summary of Matthew’s talk.)
What Chuck is doing is entirely consistent with the MVD concept. He’s creating exactly as much content that he needs to answer his customers’ “how to” questions. Would screenshots help that? Sure. But if they aren’t absolutely necessary, then he doesn’t need to include them. He can spend his very limited time on the required tasks: creating the content, validating it against the product (which is being developed at the same time), getting the content reviewed, and then doing whatever he needs to do to get it published. All without causing delays to any other part of the schedule.
Minimum, but viable
I really do hate the idea of skimping on screenshots. But “minimum viable X” is a key concept of lean software development. And documentation without screenshots can certainly meet the “viable” condition.
The documentation needs to answer questions as quickly as possible, whether that’s “how do I do X with the product?” or “can I do X with this product (and do I want to buy it)?” In an Agile environment, we need to create content that anticipates and answers those questions as quickly as we can, and then move on to the next piece. Especially if a writer is a member of multiple teams (as is common), there’s never enough time in the schedule to make each piece of content perfect. “Viable” is a much more realistic goal.