A Reverse Approach to Help Authoring: Writing Documentation Post-Release

When I first started as a technical writer, a senior writer taught me how to write documentation. Her approach, which aligns with the traditional way of doing technical writing, generally followed these steps:

  1. Get involved as early as you can in the software development process. As soon as prototypes are available, or a functioning development environment, start the documentation process.
  2. Think of all the main tasks users will do with the application. Make a list of the tasks and begin documenting them in careful detail.
  3. As the application nears release, finalize your help material so that it’s ready when the application launches.
  4. Once the application launches, move on to another project.

This traditional method of writing documentation places all the work before release. Sometimes I think the bulk of documentation should be written after release. This “reverse method” aligns more with support center philosophy. Some support centers believe you shouldn’t write anything until a user asks a question. Only then do you begin to document answers.

The Reverse Approach to Documentation

With a reverse approach to documentation, you place more emphasis on the help material after the release rather than before.

But you might object and say that our job is to anticipate the user’s questions and pain points so that when they do search the help file, the answers are there waiting. This in fact is Ginny Reddish’s premise in Letting Go of the Words. She encourages us to imagine a conversation with the user, anticipating their questions and responding as if in conversation.

I think imagination, even user interviews, are good techniques. However, too often I skip over this. I end up giving nearly every topic equal attention, documenting with careful detail both the obvious tasks and the difficult tasks. My imagination is usually an extension of the product manager’s vision and understanding, which I inherit from dozens of project meetings. The closer and more involved I get into a project, the less clearly do I see all the assumptions I’m making, the workflows I’m immune to, how blind I’ve become. No one can predict the future. How often have our anticipations and imaginations perfectly matched user reality? Do we even know the user’s reality?

With the traditional method of documentation, after the application is released, I’m not as closely involved with the project anymore. I don’t have my nose in JIRA; I’m not carefully monitoring all the incoming feedback. In my mind, I’m done. User pain points and frustrations often go unnoticed, while my attention shifts to new projects. I may add a topic here and there, or add some more detail, but by and large, documentation is mostly done when the application is released. I think that’s a harmful mentality that might be cured by a more reverse approach.

Let’s rethink the model. With a post-release documentation emphasis, the technical writer pays careful attention to every incoming question, comment, and feedback item from users. Whether through support center calls, forum questions, feedback emails, webinars, or other channels, the technical writer carefully monitors each question and begins building the help material from these questions. User feedback drives and shapes and structures the help material. It determines what we write, how much emphasis topics receive, and how visible we make those topics.

Now I’m not an extremist. I know that some help material is necessary when an application is launched. Quick reference guides and some basic help material would probably suffice. It would give something to the user to get started and not feel alone or abandoned. In some cases, a short series of video tutorials might also be helpful. After all, users need the most help when the application is newest to them, that is, when it’s first released. Abandoning the user in their time of greatest need may seem somewhat cruel and unproductive. I’m not saying no documentation should be written prior to release.

And yet, the long help file can wait. Wouldn’t we be much better to start writing help in an intensive, 100% heads-down manner during alpha and beta testing periods, and then during the first month of release? After all, how much time do we waste trying to figure out how a partially-built, bug-ridden application works in an unstable development environment? Wouldn’t our time be better spent waiting for the application to reach a near-production level, and then once that level is reached, focus all our energy on creating help material for it, based on questions and issues and frustrations users are experiencing?

Without a launch date for an application, there’s no clear date when documentation is done. In this post-release, reverse model, documentation can keep growing as long as users continue to ask questions and experience frustrations. Documentation is probably finished when the incoming feedback dies down, when most of the incoming questions can be answered with simple links to answers in the help.

Feb 3 update:

Check out this video from Greg DeVore that expands on some of the points I make in this post:

For a contrasting perspective on the idea of reverse documentation, see this post by Kristi Leach, When is it time to hire the technical writer?

Madcap Flare Adobe Robohelp

This entry was posted in general, writing on by .

By Tom Johnson

I'm a technical writer working for The 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS or by email. To learn more about me, see my About page. You can also contact me if you have questions.

69 thoughts on “A Reverse Approach to Help Authoring: Writing Documentation Post-Release

  1. Greg DeVore

    I like this a lot and it falls in line with what we have been telling our customers for quite awhile now.

    We tell our customers a lot of things but as we have gone back and interviewed the most successful ones, without fail, they mention that this approach of creating documentation after release has been the biggest key to their success. It completely changes the way you write and use documentation.

    And you are right. You can’t launch with no documentation at all. But you can launch with a minimal set and then grow it as needed.

    Question for you though – how has this affected the tools you choose to use to author and deliver your docs?

    BTW – we just posted a video that discusses this type of approach this morning on our blog:

    http://www.bluemangolearning.com/blog/2012/02/docs-that-rock-whiteboard-video-do-it-dont-finish-it/

    1. Tom Johnson

      Sweet video. I added an update to the post and embedded the video. I really like your approach. Thanks again for creating and sharing the video.

      Re tools to author and deliver, yes, this approach definitely affects that choice. I use Mediawiki. This accommodates being to quickly go in and author and update documentation on the fly. I don’t think this approach would work well with a standard HAT that requires you to compile and generate and publish each time.

      1. Greg DeVore

        Thanks for adding it. Regarding tools – web delivery is really the only way this works. Sending out updated PDF files to everyone isn’t going to work and really kills the whole workflow.

        That is great to hear that you are using this approach with new projects. Would you say that you find this approach more enjoyable? I really feel that it gets you more involved with the overall success of the project. This is important for two reasons:

        1. It is more fulfilling to be helping people instead of just writing to requirements.
        2. At the end of the day you become more valuable to your organization. You are able to make a real impact. That raises your profile in the org and makes everything you want to do much easier.

        Interested to hear your experiences with this.

        1. Tom Johnson

          Greg, I am glad to read your comments on this thread. It seems clear that for some, this reverse approach doesn’t work. But you bring out some real advantages to doing so — ones I hadn’t thought of. It is more fulfilling to be helping people, rather than just anticipating future user questions. And I do think it makes me more valuable. Thanks again for commenting on this thread.

  2. Mark Baker

    Hi Tom,

    I agree completely and have been arguing the same thing for quite a while now. A few of my key points in this argument are:

    - Releasing all the information at product release is an artifact of the economics of paper. The only real argument for stopping content creation at product release is that it is too expensive to update paper docs after the fact. It is purely an economic necessity of the age of atoms that has no place in the age of bits.

    - Most of the information about a product is created after its initial release as a result of people using it for real world tasks. Stopping content creation just as information generation is ramping up makes no sense.

    - Increasingly, products are not standalone, but nodes in a network. Information about the node changes as information about the network changes. You have to keep on documenting the product to keep up with its changing role in the network.

    - Increasingly, products are not bought but subscribed to. Products update themselves regularly as long as the user remains subscribed. Content is an implicit part of this subscription and should be maintained as long as there are subscribers.

    - All community content about a product is created after release. If the writer wants to have any role in the community content process, they have to be involved post-release.

    1. Tom Johnson

      Mark, I’m glad that you agree with the same approach. You make a lot of additional supporting points that I hadn’t thought of. I especially like your point that “most of the information about a product is created after its initial release as a result of people using it for real world tasks. Stopping content creation just as information generation is ramping up makes no sense.”

      By the way, I completely followed this method yesterday with a simple app we released. We were able to document pretty much everything in a day. Worked well.

  3. Helen Abbott

    Love this, Tom. The tricky thing in our situation is that many of our customers are “closed shops”, for example in the military, with no internet access. So despite the fact that we write all user docs in a wiki, all of our docs have to be packaged with the tools. We do continue to update the docs after release, and the updates are packaged with service releases, but providing only minimal docs with the release will not work. Would love to hear other readers’ thoughts on this problem.

    1. Mark Baker

      I wonder if this is the kind of situation that could be address by some kind of VPN arrangement. If a regular help system can phone home over the Internet, could not a help system in a secure environment phone home over a VPN? Obviously it would depend on the client’s security policies, but secure environments do generally require some avenues of communication with the outside world.

      In a recent webinar, Sarah O’Keefe and Char James-Tanny asked what the next round of innovation in HATs might be. VPN support maybe?

      1. bg

        “with no internet access”

        Obviously, no Internet access also means no VPN.

        In my experience, many large companies have very rigid guidelines who can connect into the company from the Internet. Every Internet connection is a potential risk, and documentation rarely is worth it (in the eyes of the company and also my own).

        1. Mark Baker

          Depends if “no internet access” means no physical connection or simply locking out ordinary access for employees. My thought was not that the vendor would push content to the customer, but that the help system would call home periodically to update itself.

          But you raise a good point about whether a company would be willing to make any kind of security exception for documentation. A case could certainly be made for it, though. The biggest security holes are often created not by system configurations but by user errors. If people do the wrong thing because they have out of date docs, that could create a security hole. And if people are frustrated by their inability to find things in the docs, they might use unauthorized channels to find the information they need, which could open up other vulnerabilities.

          Making sure people have correct, complete, and up to date information could potentially have sufficient security value to justify opening a channel to receive doc updates.

    2. VS

      Helen,

      One way of updating your clients would be to let them host your doc system behind their firewall, and send them regular delta files for keeping the documentation current (the way out-of-date desktop softwares notify you for upgrading).

      Another way is perhaps letting them receive RSS feeds through a secure channel.

      I’m sure there are plenty of other options out there, but these are the ones that came to my mind right away.

      VS

    3. Tom Johnson

      Not having internet access poses a serious problem to following this method. In this case, it probably wouldn’t work well. You would have to just update the content during regular application release windows. I do not have those requirements, though.

  4. Christine Astle

    I would love to be able to continually improve the user assistance content, adding more information where needed, focusing on the topics that customers ask about most (and correcting errors found post-release).

    However, I have a similar response as Helen. This approach would assume that your organization has the processes in place so you get that feedback and that updated/enriched content can make it to the users (or that the will exists to set up these systems).

    1. Tom Johnson

      I have been authoring on a live wiki long enough that I have almost forgotten other methods of publishing help content. Sorry that I didn’t account for these difficulties more fully in the post. You’re right that they do pose serious challenges to a post-release emphasis with documentation.

  5. Leigh White

    Excellent post, Tom. Every tech writer can attest to the mountains of time that have been wasted documenting features that didn’t make the release, or re-documenting features that completely changed course during development. Moving the bulk of documentation efforts to post-release makes so much sense. In theory, anyway. To accomplish it is not only a documentation shift, it’s a corporate mindset shift as well and there are obstacles. I think it’s typical (of software companies, at least) to document the kitchen sink and provide it when the release goes out–whether it’s all necessary or not and whether it meets client needs or not. There’s a security blanket mentality in being able to point to that huge online help file or PDF and say, “there it is.” Many larger clients of software companies have the clout to demand full documentation as early adopters or beta clients, making it impossible to shift the documentation effort. If documentation is tightly integrated into the application, that may also make postponing the effort impractical. The first issue is one that could possibly be overcome with some savvy spin to those clients. The second issue is more technical and harder to overcome and some other responses here allude to the same thing. As with everything, sometimes the smart solution is possible and sometimes it’s not.

    1. Tom Johnson

      Leigh, thanks for your insight. I agree that if help is tightly integrated into the user interface, you can’t delay the documentation until after release. Also, I can see that clients might demand full documentation when they initially receive the product. Good points. Maybe I should emphasize more that the alpha and beta testing periods are when documentation should kick into high gear. Then again, maybe this approach is too impractical regardless.

  6. Mariann Foster

    Great article. I also think this method would be a much more effective use of time. I don’t know how many times I have had to re-write section, re-take screenshots, and re-do training modules because the software GUI changed during Beta.

  7. Greg DeVore

    For those who have raised issues about having to package docs in the tools – it can seem like a show stopper for this type of approach and can be difficult to workaround.

    One thing we did a long time ago when we were working with medical device manufacturers was to setup a “pull” system for the docs. Basically it did the following:

    1. Docs were embedded when the system went out.
    2. We had private web area where we could post updates.
    3. The docs in the delivered app would routinely poll the private web area for changes.
    4. If changes were found the app would import those changes.

    It isn’t quite as responsive as what Tom describes but it was much better than just shipping and forgetting.

    1. Tom Johnson

      Thanks for adding this tip. The pull method sounds like it was a custom script. It’s cool to see these kinds of customizations integrated into the documentation process. I still prefer authoring on an online wiki, though. It’s just so much easier to update information immediately.

  8. Jessica C.

    Hi Tom,

    Another great and thought provoking post.

    Your comment here hit home with me:
    With the traditional method of documentation, after the application is released, I’m not as closely involved with the project anymore. I don’t have my nose in JIRA; I’m not carefully monitoring all the incoming feedback. In my mind, I’m done.

    I’m one writer in a department with four teams. I’ve got work waiting from another team when I complete a release. I simply don’t have time to wait for a release for documentation. Although it would be great, its just not practical.

    1. Tom Johnson

      Jessica, thanks for your comment. One question I have is how you measure success with documentation. How do you know if the documentation you wrote solves customer problems? It seems like that kind of metric or monitoring would be important, and would factor into some kind of post-release treatment of the documentation. If the documentation succeeds 100% of the time, there’s no need for a post-release edit of the documentation. If so, congrats. However, in my case, there is definitely a need for post-release editing. It’s hard to measure the success of documentation, so this analysis is often overlooked.

  9. Tammy P

    I hate to be out of step with the rest here, but I have serious concerns about this approach. The biggest is that once users have gone to the help or docs (which is far more likely when a release is new to them) and *not* found an answer, they are less likely to come back – they’ll look elsewhere. So you lose your ability to help them in the future and save them and your company time and money. I think increasing our emphasis on improving docs based on customer feedback after a release is essential, but I don’t think releasing with minimal docs and then filling in the details later is the way to go. Sorry!

    1. mma

      Tammy raises a great point. While not all new users to our product use the documentation, a great many do. There perhaps is a question of degree here. Neither the post nor the video claim a company should release without _any_ documentation.

      So, how much and what kind of documentation should you release? My answer would be “release enough documentation to make the average new user successful with your feature or your product.”

      The reason you want to do this, is:

      * You want to teach your reader that the docs can help (nods to Tammy). Why? Simple, an answer in the documentation is cheaper than an answer from a support person or a dev.

      * You want the product to make a good impression so people buy it/use it. Very few products can users use without any documentation. Documentation is part of the product. If the entire product fails to make a good impression, what are you teaching the user?

      * You want to participate in the product design process early and often. There is value for the reader and for the product in having the writer participate and learn early. You can’t determine what is “enough to make the user successful” without first making yourself successful. You can find that out by participating and you can improve the design at the same time by being a tester.

      Waiting until others ask the questions or make the support calls may inform you as to what to write but it doesn’t help the reader. It seems to me all that will, in part, just leave the reader waiting for the process to produce output he/she can use.

      1. Greg DeVore

        You are right that launching with “no” documentation is a bad idea. But launching with a very minimal set works fine.

        The fact is, most products don’t have a massive influx of users from day 1. They have a few beta users and then they launch and people begin to use the product a little at a time. If you are responding quickly then you will have a pretty good set of documentation the first day. The few users who had to ask questions will appreciate your responsiveness in creating answers to their questions. The rest will assume that the answers have always been there.

        But your ability to respond quickly is key. When a question comes into us we create a new help article and publish it in about 5 to 10 min. We then send the response to the customer. If it took us 2-3 days or a week then this approach would fall flat on its face.

        From our experience you can get a lot of documentation created in just a day or two using this approach. Then you just add updates over the next weeks and months as needed.

        1. mma

          Greg,

          I would a agree a minimal set can work just fine. So, we should drive toward finding techniques that identify this minimal set.

          To the “massive influx of users” point…I’m not sure it makes a difference how many users are there on release day waiting. IOW, whether it is 5 or 500, I want my minimal documentation to make those 5 people successful.

          Just one of those 5 happy customers may have a Twitter feed of 500+ and if that person tweets — “Wow got up and running Foobar in just an hour” — well that is pretty beneficial to a product eh?

          1. Tammy P

            It was the minimal set of documentation that I was arguing against – I did understand that you were not saying you should release with no documentation. My concerns still apply – with minimal documentation, some of the problems that users will run into will not be answered – problems that could have been answered with more complete documentation. And I don’t think at that point that they’ll come back. Not all users are impatient, but we are all jealous of our time and want to go somewhere where we’ll get the best answers.

          2. Tom Johnson

            I think my point was that it’s impossible to anticipate all the issues and questions users will experience prior to release, so no matter how much time you spend developing documentation before releasing your product, you’ll never hit that target in which users find the answer in the help. You only get to that point once you begin to see the questions and issues arising, and then adjust your help accordingly.

          3. Tom Johnson

            Sometimes these alpha users, though, are more tech savvy and don’t necessarily need as much help as the later users.

            Overall, this is an interesting discussion. There are a lot of post-release dynamics that I think we often ignore by moving onto other projects after release.

        2. Tom Johnson

          wow, monitoring these incoming questions and then posting every 5-10 minutes seems like extreme documentation — and it sounds like a lot of fun. Thanks for sharing your experiences here, Greg.

      2. Tom Johnson

        mma, thanks for your comment. I think you summed it up nicely here:

        So, how much and what kind of documentation should you release? My answer would be “release enough documentation to make the average new user successful with your feature or your product.”

        Of course if the documentation already makes the user successful, what need is there to edit it post-release? I imagine by “successful,” this is a spectrum measure. One can become more successful with some moderate tweaks and adjustments to the documentation?

        I guess this also points out that we have to be able to measure how successful documentation is. This is probably the topic of another post, but surely this is a metric that we should be measuring with our documentation. Is our documentation successful, and if so, how do we know?

    2. VS

      Agree with Tammy. A lot of enterprise customers who’ve likely paid a good amount of money for your software solution will not be happy to be left without help the first time they try to work on a software. Also, a lot of people use softwares on trial basis, to see if it is a good fit for their team. If these early testers find that the documentation is threadbare, they will just drop your software and go to a competitor.

      Some of the problems Tom was facing (not knowing what features/tasks the users might find trouble understanding, having to document ‘everything’ in a flow) might perhaps be curtailed by adopting a cookbook/wizard/task-based approach to documentation.

      Map all the possible tasks a user follows in your software, and document the concepts and procedure for only these tasks to start with. This approach might let you prioritize the tasks that are most important to your users, while you leave the unimportant or easy tasks to be documented in the end. You can also add further tasks, error scenarios, and fringe possibilities after the software release to augment the already published documentation.

      VS

    3. Tom Johnson

      Tammy, good point here. Is the initial trust with the user broken when the help material is incomplete? Hmmm. Hadn’t thought about that.

      One solution might be to provide an easy way for users to submit feedback and questions. Also, maybe upon initial release, the help should be more developed. But if so, how do you avoid spending too much time documenting the wrong things? You only truly know everything that you should emphasize post-release. Maybe I should argue more for an evolutionary mindset with help prior to release.

  10. Milan Davidović

    What are your thoughts on the costs of this proposed approach vs the traditional one you’re contrasting it with? How would you gather and analyze data to research the costs?

    1. Tom Johnson

      Milan, good points. How would I analyze the costs? I haven’t thought about that as much. Metrics surrounding costs are one area that I need to develop more. If support calls are the only indicator of documentation costs, then it would probably integrate with that metric. I haven’t thought this through, though. If you have any insights, please share them.

  11. Jonatan Lundin

    Nice post Tom. The point you’re making is very well aligned to what I’m trying to say, namely that technical communicators are actually answering questions. This is since user are active and at some point end up in a search situation, where they have questions. This has been discussed some week ago here: http://technicalwritingworld.com/forum/topics/current-trends-in-documentation-structuring

    My next blog post will discuss the role of technical communicators in the “answering questions” perspective’. What type of questions do users ask? Can a manufacturer predict them (pre-release)? Who shall/can answer them? Where do we (the manufacturer/other users) make them findable for users? Where to technical communicators come into the picture?

    A complete reactive post release approach has some interesting challenges for technical communicators. What is the difference between the technical communicator and the support/help desk people? Do the technical communicators collect answers from support/help desk and put them into the traditional PDF/help files? I guess the traditional approach to deliver static manuals is not going to work. Do you update the manual and send it out to all users each time you have answered a question or after 10 questions are answered or after 100 or…? How do users find the answer among maybe thousands of other answers in the manual?

    1. bg

      Personally, I think that the classic (as complete as possible) manual is mostly written _for_ the support team and the future developers that come late to the project.

      If you don’t have a place where all those little options, buttons, quirks and limitations of software are documented, the knowledge about the details will quickly get lost in time.

      1. Tom Johnson

        bg, Mark Baker pointed out how some advanced users who read the manual will teach the masses who do not, so even if it’s just the support team and developers reading the manual, these key influencers can still get this information out.

    2. Tom Johnson

      Jonatan, thanks for your comments. The only way this system would work, in my opinion, is with a platform like a wiki, which is not meant to be printed but rather searched. If you’re compiling all of this information into a PDF that grows larger and larger, the method would fail. But I don’t think that long manuals in the form of a PDF are what we should be delivering anyway. People search online for information they need. They may want some printed documentation, but not an encyclopedia full of information. Besides, information changes too rapidly to make it worth the cost of printing.

  12. Sagar

    I really liked the way how you expressed general happenings in a Technical Writer’s professional career. Truly, each and and every line carries my inner thoughts and some time transformed to frustrations.

  13. Jim

    Good article, I will borrow some parts of it and translate it to Swedish. Of course give you a link back to this article as well.

    Thanks,
    Jim

  14. bg

    the traditional way of doing technical writing

    I think I’m spontaneously happy that I am one of those lateral entrants who didn’t get told how to do it the traditional way :) I’m a freelancer in software documentation and I’m mostly called for projects where the product is already on the market and badly needs more&better documentation or online help, or the product is shortly before the launch and the documentation is a pressing need.

    When techwriters are very early involved in the software documentation process, there’s a high chance of redundant work. The worst case I saw was a writer who tried to keep up with the scrum cycles of his team. I think that writing user documentation for each iteration is way overdone, as the software and especially the frontend keep changing so much.

    It’s good when the techwriter starts writing before the release because then you can still give feedback on usability and software bugs to the developers, but too early, too much doesn’t make the documentation necessarily better. Especially – as I agree with you – being too involved means developing blind spots and losing contact with the users’ problems.

    1. Jonatan Lundin

      Sometimes I hear people (technical communicators, SMEs etc) say that you should write the manual first and then develop the product. Meaning, to treat the manual as the product design specification. Is that pre-pre release?

      I also often hear many technical communicators say that they need to be involved early in projects to not end up as the last project activity. I don’t think any technical writer wants to work in a “ketchup effect” mode.

      You must take the users and their product knowledge, mental models etc into consideration, when deciding on doing either pre- or post-release documentation. I guess a new product launched on a global market targeting users, completely unfamiliar with the technology, where the GUI doesn’t look like anything you’ve ever seen before, could benefit from having something more than just a minimal manual set.

      But, if the product interface can communicate its use (afford its use) then a manual is not needed. I guess this is the case with the Iphone, Ipad etc.

      1. Tom Johnson

        Sometimes I hear people (technical communicators, SMEs etc) say that you should write the manual first and then develop the product. Meaning, to treat the manual as the product design specification. Is that pre-pre release?

        I think I once heard this, but I have never seen it done before. If anything, that manual is simply a waterfall-like business requirements document.

        I also often hear many technical communicators say that they need to be involved early in projects to not end up as the last project activity. I don’t think any technical writer wants to work in a “ketchup effect” mode.

        Yes, this method will land you into a crisis-type of writing situation, one that technical writers tend to loathe as they feel they’re always being invited late to the party. However, my premise is that you won’t know what to write if you come to the party too early.

        By the way, I think you meant “catch-up” rather than “ketchup,” but I like the image of the latter spelling.

    2. Tom Johnson

      bg, thanks for commenting. I appreciate your insight as a freelancer into this scenario, and I’m glad some of the points resonate with your own experience.

      The point you make about not keeping up with each scrum release is interesting. Immersed in an agile environment as I am, I’ve often thought that I should be keeping up the documentation with each scrum release, but you’re right — this is kind of a waste of time, since interfaces and functionality change so much with agile processes. Thanks again for your comment here. I hope to hear more of your insight in the future.

  15. Mark Baker

    Perhaps another way of looking at this question is not to ask, should we release some of the information after the release date, but, is it actually possible to deliver all the information that users need on the release date? I would suggest that the answer to that is usually no, for several reasons.

    * Products are being developed and released faster than ever, driven by market windows that snap shut on any late entrant.

    * More and more products work in a network environment rather than standalone. The network is too vast and complex to anticipate all the interactions the product may have, and those interactions will change when other nodes of the network change.

    * Products are increasingly being updated on the fly.

    * Minimalism and a focus on UX have caused tech pubs to move away from the traditional meaning of documentation (to describe the product) towards task orientation. But in many cases, as many writers have rightly complained over the years, it is not possible to anticipate the tasks that users will attempt until after the product is in their hands.

    If we turn the question around and ask, is it possible to provide all the information necessary to support users tasks before the product is released, it may give a different perspective on Tom’s point.

    1. Jonatan Lundin

      Curious as I am, I wonder if you could give some examples of tasks that are not possible to anticipate until the product is in the hands of the user. Could it for example be a user who attempts to use a product for something is was not intended, such as when a user wants to use a mobile phone as a frisbee?

      Some users sometimes thinks a product can be used for something else than the intended use. The result is that a user wants to do tasks the manufacturer couldn’t dream of prior to the release. If I’m following you correctly here, it then seems very difficult to deliver all the information that users need before the product is released.

      1. Mark Baker

        Johnatan,

        What is the “intended use” of a programming language, or a function library, or an operating system? Most of what technical writers document these days are tools, components, systems, or devices that operate in networked environments. Can you anticipate every possible interaction with every other tool, component, system, network, or device with which a product may legitimately be used, even those that have not been created at the time the product is released, or have been updated after the product was released?

        The last time I documented a product with of fixed and countable set of functions and interactions was 1995. To quote Ted Nelson:

        “Hierarchical and sequential structures, especially popular since Gutenberg, are usually forced and artificial. Intertwingularity is not generally acknowledged—people keep pretending they can make things hierarchical, categorizable and sequential when they can’t.”

        In a networked world, Nelson’s statement is not only true of knowledge, it is increasingly true of things as well.

        1. VS

          Mark,

          I believe Johnathan makes a good point about how the software designers design software for specific purposes. But I also see your point in interacting software units that are built by different vendors. Even in such scenarios, software designers and BAs usually design these interactions to work within a certain bandwidth. These bandwidths are usually well within the reach of tech writers to document. No doubt that there will always be fringe activities and McGyverings that nobody can predict. My point is that the types and numbers of complex interactions between different softwares are by design finite, and so should not be out of reach of tech writers. (You will note that I have not said anything about publishing time frames here).

          Iterative publishing will nicely fit in here when you must document how your software will work with another upgraded software/OS, etc. But in these cases, the softwares are updated as well and so the docs can also (usually) be published concurrently. So it’s not so much as a doc iteration, but a software upgrade that you are documenting.

          VS

          1. Mark Baker

            VS, interactions may be finite, but it does not take very many independent variable to make the possible interactions number in the billions. This is particularly true when you are dealing with software tools rather than end user products, though it can easily be true of end user products as well. I worked on one fairly simple web application for which we calculated that something like 100,000 possible outcomes existed for a five or six step process.

            Now, these potential outcomes tend to be a sparse matrix. Of the billions of possible interactions, maybe only a few dozen will occur with regularity in real world use. It is doubtless possible to anticipate some of these, but generally, not all of them.

            But whatever the math tells us, real world experience tells us that technical writers, product managers, and product developers frequently fail to anticipate the ways in which products will be used once they are in the market place.

            Jonatan believes that his SeSAM provides a means for accurately anticipating those missed uses, whereas I believe that his approach artificially excludes from consideration many of the real-world tasks and issues that users encounter — a debate that we have had a number of times.

            Though I disagree with Jonatan on his approach, I do applaud him for grappling with the problem, which is the same problem that Tom is grappling with in his post.

            My belief is that the user community has (for many products at least) already solved this problem for themselves through communities and forums on the web, but that much scope remains for professional technical communicators to work within and to enhance the model that the community has already created.

          2. Tom Johnson

            My belief is that the user community has (for many products at least) already solved this problem for themselves through communities and forums on the web, but that much scope remains for professional technical communicators to work within and to enhance the model that the community has already created.

            Interesting. I didn’t know your thoughts on this. Can you expand on this, or point me to a place where you expanded on it in an existing post? I am curious to know more.

        2. Tom Johnson

          Thanks for responding, Mark. That’s an interesting quote from Ted Nelson. Where does it come from? I hadn’t heard of intertwingularity before, and it sounds like something I want to learn more about. I’m assuming it’s just a word that describes how intertwined and tangled things are. I agree that any product (that is somewhat robust) will have a seemingly infinite number of users.

          1. Mark Baker

            I was reminded of the word intertwingularity recently by one of David Weinberger’s books. I got the quote from the Wikipedia article on intertwingularity, which attributes it to the revised editon of Computer Lib/Dream Machines.

      2. Tom Johnson

        Jonatan, I like that you’re questioning one of the fundamental assumptions about this scenario: why can’t a technical writer know all the issues and questions users have? I suppose one could do enough research to do a better job of anticipating. I think your larger point is that we shouldn’t try to write for non-standard uses of a product, and that the standard uses of a product are fairly well-known. I think this depends on your product, really, and your users. If your users all fit a very similar mold, background, and business environment, then you could probably better predict all of their questions and issues. But if your users are more varied, then the problem of anticipation becomes much more difficult.

        1. Jonatan Lundin

          Hi Tom. I do believe that there are two sides of the “prediction” coin. Some questions are possible to anticipate and some are impossible and must be answered post-release (see example below).

          Many of the questions, that I believe can be anticipated, arise when the user is trying to understand the intentions of the company developing the product: What can this product do (can it do what I think it can)? How do I use it to make it do what it can do? Do I have to do X? These types of questions arise when the mental model of the user is not 1:1 with the product design. Then, if these questions are asked at all depends on what mental models and knowledge the users actually have. If all users have a 1:1 mental model, then no questions are asked. As you say, if users are more varied, the more varied are the number of possible “different” mental models.

          As a technical communicator you have a responsibility to tell what the product intention is and what it can do for the user. But that is not enough? As Mark points out; we can’t know the user intention. Let’s look at a user wanting to use the product for something the manufacturer couldn’t dream of (connect it to make it work with “Y”). The user reads the manual and finds out that the product can be connected to work with X. Aha! Says the user and concludes: “But the manual doesn’t actually say that the product cannot be connected and work with Y. So maybe Y is possible? So the user tries to connect the product do Y. User fails and sends a support request to the company.

          Technical communicators should not only tell about the product purpose but also about what it can’t do. And the “can’t do” statements should be updated as the world around us is changing post release. This is of course not something a company wants to do, but I guess it would help the user and reduce some of the post release questions. Be explicit!

          BTW; why not use the company support database to evaluate the predicted questions? Or, give the support people a list of questions you intend to answer pre release and ask them to give their opinion. Or even better, merge the CMS and the support database into one coherent whole. And make the whole thing public (and searchable)!

          1. Tom Johnson

            Jonatan,

            “Technical communicators should not only tell about the product purpose but also about what it can’t do.”

            I have started adding a “Known Limitations” section to my help material. It lists design shortcomings, known bugs, or other features people always ask about but which the product lacks. I think it’s a valuable addition.

            “Or even better, merge the CMS and the support database into one coherent whole. And make the whole thing public (and searchable)!”

            That would be idea. The problem is that support centers use knowledge base / incident management systems, and technical communicators use HATs. I have tried merging these in the past and not got traction on the idea.

            By the way, I can’t remember, but did you say you’re a PhD student?

          2. Jonatan Lundin

            Hi Tom, I agree that there are many obstacles in merging techdoc and support content. I don’t know if there are any CMSs that have a “support case” add-on. If not, someone should look into it. I’m thinking of talking to DITA folks about including a specialization to be able to manage support content (something like the learning and training specialization).

            Yes, I’m a part time PhD student (just started 1st of sep last year). I’m currently trying to map out the research frontier regarding information behavior, information seeking behavior and information searching behavior (or information retrieval). There are a lot of knowledge available out here that technical communicators should take advantage of. There are many many empirical studies revealing how lawyers, doctors, nurses etc etc search. But I have not found any studies on how users of technical products do search – or even more important – how to design to increase findability. That’s where my research comes into the picture.

    2. Tom Johnson

      Mark, thanks for your insight and perspective here. I like the way you approach the question, asking whether it’s possible to know all user needs beforehand. I think that debunking that myth (that a tech writer can fully anticipate every user’s need and question beforehand) is key to getting involved post-release, however one does it. I like the bullet points you list here.

      I’m grateful for the knowledge, experience, and insight for so many professionals who have joined in the conversation on this thread. This is truly a key concept in the practice of technical communication.

  16. Jonatan Lundin

    Human beings are goal driven; there is an intention behind each human act (spoken or non-spoken). We eat because we are hungry, we work because we want to make a decent living etc.

    Users are goal driven, they want to get things done. A user is using a product, a programming language or whatever because s/he has a goal to solve a need, requirement or problem and s/he thinks the product, programming language etc can help out. Therefore, a user has an intention to use the product in a certain way. We as technical communicators cannot know the user intention. What is the intended use of a programming language? Ask the user.

    To develop a product is a human act. A product, programming language or whatever is designed for a purpose; the product manager stating requirements on development teams had an intention. The company, individual or whoever is crafting, developing or designing an entity or artifact does it for a purpose. So we can find out about the intention behind a product, programming language etc by asking the one developing it. Since technical communicators often work close to product management and development, this is an easy task to find out. I don’t think someone develops a function library without having a purpose in mind.

    A user has a mental model of the product and what it can do; its purpose. So a user is using a product or a programming language because s/he believes that the purpose of the product is in line with what the user wants to do (the goal). This is why the product was bought.

    In best of worlds the user has the same view of the product intention and what it can be used for as the manufacturer has. And in best of worlds this is in line with what the user wants to do: “I have a need to fix A. I think the product can fix A and that is why I want to use it.” Now, the product may be designed to fix A or not. The user mental model of the product may not be according to the mental model of the system designer. What happens then? A user may get stuck and an information need arises (the user is in a search situation). The user asks questions: “Can the product fix A?”

    Furthermore, all users probably know that they must do something to make the product do what they want. No one thinks a product is automatically doing what is wanted without the user interacting with the product at all. A user has a mental model of how the product must be used to make it solve the problems, needs or requirements. This mental model may not correspond to the intention the manufacturer has and the user gets stuck and need information. The user asks questions: “I know the product can fix A, but how do I make the product fix A?”

    If we as technical communicators assume that some users have a different mental model about the product and its purpose from what the product manager had, many questions can be predicted and answered prior to product release. Just a statement that the product purpose is to fix A, gives many users an answer. What would be valuable for a user is a description about what the product cannot be used to do, but often a manufacturer is not interested in revealing the drawbacks of a product.

    I agree that this is a little simplified view on what is going on out there. A user might have a need to connect a product a to secondary equipment X, where equipment X is not in the product portfolio of the company that develops product A and equipment X was introduced on market after product A release.

    The user either thinks the product can be connected or is a little uncertain. Or the user knows the product cannot be connected from a default set up, but wonders if it is not possible if some special “in-between” device is used. The user asks a question post release since the manual doesn’t say anything about it. This kind of questions cannot be predicted pre-release since we cannot know what will happen in the world after release. We can’t anticipate every user intention to interact with every other tool, component, system, network, or device with which a product may legitimately be used. This has to be answered post release which is reflected in a post release updated manual. How many questions are of this type? Many.

    So technical communicators needs to around before release to predict questions based on differences in mental models of the product purpose but also be around and update the manual after release to answer questions coming from user intentions that cannot be foreseen at the time the product was launched to a market. Why do only pre or post – why don’t do both?

    1. Tom Johnson

      Jonatan,

      I agree with your conclusion — that we should attempt to anticipate users questions before release and continue to answer them after release. Ideally, we should have enough time allocated so that we can spend equal amounts of time before and after. However, I think in the real world, getting approval to spend this much time may be problematic.

      The post-release effort really depends on the product. If the product has a very narrowly defined function, this post-release effort may not be as important as I argue. But if the product is more general and used by a greater variety of people, the number of uses for the product can get a bit out of control.

      As always, thanks for your added insight into this topic.

  17. Pingback: DocSoup Digest 003 | DocSoup

  18. Kyle

    I think the answer lies in the middle.

    You write enough to cover ever function of an application after is released for testing just prior to release.

    Then you add and edit the instructions based on your user feedback directly from the customer and support teams.

  19. Pingback: Leveraging the wisdom of the 80/20 rule: Focusing on content that matters | I'd Rather Be Writing

Comments are closed.