The case for Minimum Viable Documentation

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.

During the session, Chuck Martin (thanks, Tom!) told us that he doesn’t include screenshots in the docs.

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.

Advertisements

15 thoughts on “The case for Minimum Viable Documentation

  1. I can’t believe you won the iPad Air.

    Chuck’s last name is Martin, I think.

    Re minimum viable content, it’s an interesting approach. One question I have is whether certain corners are cut without justification. It doesn’t take very long to add a screenshot. It takes more time to create a concept diagram. And even more time to create a video tutorial. And even more time to create an e-learning course. So we all scale back somewhere. Knowing where to draw the line is tough. I am a big fan of visuals. If the application is changing to much than screenshots relevant one day are outdated the next, then that is one heck of a release cycle.

    1. I agree; it does seem like you’d never be able to create videos, or else you need to rely on another team to do that work.

      I think it comes down to exactly what “minimum viable” means to your organization. If “text and nothing else” isn’t enough, then that’s a case to hire more people to work on the documentation (help, illustrations, videos, API docs, etc.). The alternative is to accept that the documentation will lag behind product development. Chuck pointed out that this becomes a big problem when developers and QA are asked to review something they worked on a few weeks ago and will only glance at the documentation before signing off on it and getting back to their current task.

      Maybe the solution is some method to hold them accountable for delivering good reviews. I’m just not sure how feasible that is.

      (Thank you for identifying Chuck! And I still can’t believe I won, either!)

  2. (I’m posting this comment on behalf of Vinish Garg)

    I am a big fan of MVC, possibly because I work mostly with startups. A majority of startups have their own limitations and priorities and MVC addresses their immediate documentation requirements.

    However, I think that ‘not including screenshots’ does not necessarily mean that it is part of MVC strategy. I worked for Basware in 2008 and they have huge enterprise scale products (invoice automation, e-procurement). We used Arbortext Editor and while working on my first task there, I was shocked to know that the documents did not have screenshots. My DM, Anne Tolonen explained it to me that each topic explains the user how to reach a particular screen, interface, or dialog box. The help is integrated within the system itself and when a user refers to a help topic, the user can already see the same interface in the application, so including the screenshots was not required. In addition, the context-sensitive help topics were also there to address quick questions. I was not too convinced in the beginning, but it got internalized later. (I wish I could share 1-2 screenshots here to share how the context was setup for the user, to eliminate the need for a screenshot.)

    We worked in agile and the products were huge and complex. But the argument for not using the screenshots was not that the development and iterations were fast paced and that screenshots would add to the task; these were excluded purely because these were not required.

    So, the documentation strategy was not based on MVC, but there were no screenshots. I worked on another client in credit repair, who discouraged using screenshots in the online documents.

    I also recall a related and excellent post by Mark Baker few weeks back, as ‘In Praise of Short Term Thinking’ (http://everypageispageone.com/2014/10/20/in-praise-of-short-term-thinking/). He says ‘rinse and repeat’ and he makes an excellent note on MVC as “minimal viable content should be about releasing content as quickly as possible to gauge reaction, and then releasing more/better content as long as it continues to yield positive revenue growth.”

    This is the basic objective of MVC.

    -Vinish Garg (@vingar)

  3. I agree with you – no screenshots does impair the quality of the documentation. Does text-only provide the user with the information they need? Yes, in most cases it probably does. But what if you have a reasonably lengthy ‘concept’ topic with no screenshots? The amount of text could deter people from reading it at all. Images can also help the flow of the text in a topic.

    But I see a lot of documentation that is purely instructions, without any conceptual stuff at all. If that’s the case, maybe the no screenshots policy works okay to a degree. But I think you need the conceptual information to give users the ‘bigger picture’ so that they learn ‘why’ and ‘when’ not just ‘how to’.

    Plus, as Tom said, it doesn’t take long to take a screenshot.

    1. “Plus, as Tom said, it doesn’t take long to take a screenshot.”
      But if your software and documentation are being localized, and you need to have that screenshot available in 20+ languages, maybe you begin to see things differently 😉

  4. You can always ship a “minimum viable” document and, once the GUI has stabilized, go back and add screenshots. Just make sure that “screenshots” is covered in the project backlog.

    1. I agree, and I think a continuous improvement process is the ideal. That’s how I work now. But if the pace of new/updated features is too great, those “nice to haves” get pushed further and further back.

      Minimum Viable Documentation (or Content, as Vinish Garg suggests) is exactly what it says: the absolute minimum that must be done. And unless we can show a clear return on investment on the time we spend creating screenshots (and as Isabelle points out, that can involve a lot of localized images), then screenshots definitely fall outside the minimum. As much as it pains me to admit that!

  5. Do we handle it differently when we move from dev to prod?
    Of course, in the Agile dev phase, stuff changes quickly. You can do without the fancy stuff, the users are testers or a pretty special sub-set of the intended user audience.
    Once the system is stable and we’re training and supporting users, you can recognize where graphic aids (such as screenshots) are needed.

  6. Hi
    Thanks!

    A colleague of mine shared this link with me. I was surprised to read about MVD as I had been talking about it since the end of last year without knowing that it was a known concept. I was very interested in your comments.

    I am currently working in an Agile/Scrum framework and the question of documentation keeps arising. Currently, we repeat what has been the norm for many years, big user guides, reference guides, and many others in a printable format without really knowing what is really used or needed. My experience has taught me that not all content is read. In fact some are never read. Hence, my use of minimal viable documentation or minimal usable documentation as I also like to call it. MVC is a new one and quite appropriate as we speak in terms of content nowadays.

    How to know what is the minimal is the big question. User/task analysis would be one way but in these agile times it is probably not the most time-effective way. Translating user requirements into topics or tasks is a good place to start with a minimal content just sufficient to describe the essentials. But how to get to that point?

    Pros and cons of screenshots: Having coordinated some localization projects in the past, screenshots were best avoided due to the difficulty of having to replace the screenshots in the native language with the ones in one of the target languages. Agreed this can be resolved by linking instead of embedding, but only to a point. And yes, screenshots can quickly be out of date, and thus, confusing to our users. On the other hand, if the documentation also serves a purpose of initial training where access to the applications may be limited or not possible at all, screenshots help to add some visual understanding.

  7. Neal. Dude. I love how you write about my life right now. Here are my two (or three) cents:

    1. Agile: Writing in Agile is challenging, but I’ve also found it extremely rewarding. I’ve never felt more a vital part of the team. As a lone writer, I’m a part of every scrum. Endless stand-ups have been mitigated by good project managers, good project management tools, and wise tech leads.

    2. MVD/MVC: I’ve spent the last few years dispelling the misimpression that I have a passion for 400-page PDFs. My first focus for our new apps is on “What is this?” help: immediate, easy to invoke, easy to digest, and easy to dismiss. The deeper stuff, if necessary, happens as we have time or a business need (as in “rinse and repeat” mentioned by Mark Baker via Vinish). MVD is like a traveler’s phrase book. It’s the handy resource you keep in your pocket when you need to ask for the toilet. The deeper stuff is the guidebook with pics and maps (“Where can I find a decent, inexpensive restaurant?”) and the dictionary (“How do I say ‘giant penguin’?”).

    3. Screenshots: I’m with the Chuck and Isabelle, less with Tom. I would enjoy taking Tom on a half-day journey through QA systems, beta systems, and local builds to find a current and correct version of the app with data acceptable enough to justify tweaking for presentation as a screenshot. I work with complex UIs with proprietary data and nearly infinite scenarios that render screenshots a prohibitive burden with much UI grooming and post-production Photoshop work. Plus I have to consider the requirements/constraints of single-sourcing and adaptive presentation. Plus plus every screenshot needs to be vetted for every release so the effort expended by number of images is not a linear progression. A screenshot has to be an extremely high-value proposition with clear reqs/expectations before I bust out the screencap tools. This reminds me of documenting APIs with examples. API users generally don’t care about all the things that your API can do. Like most users, they want to know how to do something right now. Few things help more than specific code/message examples, but generating and maintaining those examples can be very expensive, much like screenshots.

    1. Thanks, Phil. Those are good points, especially abut the value vs volatility of screenshots.

      Very true about API docs, too, and it makes sense in terms of what more than one customer has told me: programmers are lazy; make sure the docs give them lots of code to copy and reuse. So that’s high effort content, but also very high value.

Comments are closed.