Moving Between the Agora and the Desert

I had a conversation with a developer the other day about help material. He said that when he sees static pages, he assumes the content is out of date. He prefers forum threads because he can see the dates, and because forums contain real information from people using the product. He likes wikis because he can easily check to see when the information was last edited and by who.

One concern he had in our migration away from wikis to a help authoring tool was that the content would become out of date. Employees would move on to other projects and documentation would lag without anyone taking care to update it. At least on a wiki, someone in the community could still update the content.

Six months later, I realized that the predictions were partially right.

But merely switching tools to something more browser-based, like WordPress, Mediawiki, or some other online CMS, still doesn’t solve the problem, my developer friend explained. The content can become outdated no matter what tool you’re using. Switching to another tool doesn’t solve the underlying problem.

We can update content regardless of the tool. If you’re using a help authoring tool and uploading the output to a server, or publishing using some other CMS, or editing directly in the browser, you still have to keep a listening ear to your users and update content regularly.

Wikis might make the job of staying updated a bit easier, because you can edit directly in the browser, and if content is out of date, users may try to make edits, thus making you aware of outdated material. But whether you work in an offline tool or online tool, the hard part isn’t clicking a few buttons. It’s taking the time to stay updated with feedback, deciding how to address the feedback, and figuring out where to add more information to your help material.

I have to confess something. I miss using Mediawiki. Using a help authoring tool feels a bit disconnected with the experience of being online. There’s not a sense of a dynamic ebb and flow of edits, comments, recent changes, histories, new users, updates, linkbacks, plugins, releases, and “online-ness” like there is with Mediawiki.

But the tool isn’t the culprit behind the out-of-date content. It’s the hassle of updating the content.

For me, the hardest part about technical writing is making the mental shift about when documentation is done. Documentation is never complete, especially at release. Users continue to have questions, issues, feedback, problems, new scenarios, and concerns. If we follow a style of Include It All, Filter It Afterwards, we end up with an ongoing engagement with documentation, one that leads us to continue to add and add and add content to our documentation until we have tomes of information.

Fixing the Problem Instead of Changing the Tool

I decided that rather than focus on tools (because it wasn’t necessarily a tool problem), I would instead immerse myself in user feedback. I spent half a day reading threads in user forums, noting information that I could add to the help. After I gathered a long list of notes, I then set about updating my help content. I added new pages, rewrote existing pages, added known limitations, added even more known limitations, responded to forum threads with updates and other information, and so on.

After a day of this, I no longer had the sense that I was “offline” by using a help authoring tool that wasn’t browser-based. Instead, it was rather refreshing to take this hustle and bustle of forum activity, information that was scattered and repeated, quoted and refuted, expanded and criticized, expounded and propounded and repounded, ad infinitum across forum posts, and then to figure out — offline — how to reshape the help material with the right information to address all of these threads.

Mark Baker uses an analogy of the “agora and the desert” to describe this interplay between online and offline modes. (He’s referring to writing books versus writing online, but the analogy still applies.) An agora is a Greek word to describe a meeting place for assembly. It’s a place where ideas are exchanged and debated. Wikipedia describes the Ancient Agora of Athens as follows:

The agora was the center of political and public life in Athens. It was a large open area surrounded by buildings of various functions. The agora was utilized for commerce, political, religious and military activity. Meetings were held four times per month to enact legislation, to hear embassies, and deal with defense of the city-state. … The law courts were located there, and anyone who happened to be in the agora when a case was being heard would probably have been able to view the spectacle, though only those adult male citizens appointed by lot would have been able to serve as jurors. The agora was further the location of a temporary theater and of burial sites.

Yes, the net provides this lively medium of exchange — what some even call an “ideagora.” Forum software was designed to accommodate just this kind of conversation.

But transferring the conversation from the forum to the help content requires more than copying and pasting nuggets of conversation threads. It requires one to step back and ponder the essential points of the conversation. What common problem runs through the threads? What are users trying to do, and how can I sift this jumble of thoughts into something coherent and simple? What is the essence of this thread that has 85 posts? How can I address the difficulty users are having and provide a logical explanation and workaround?

After some contemplation in the desert, I update the help material and throw it back into the agora.

The cycle repeats again and again.

Moving Between Agora and the Desert

Moving Between Agora and the Desert

I rather like the interplay between the two modes. We can’t always live in the agora, and we can’t always live in the desert. A balance between the two mediums provides the right amount of information and interaction.

After a day of working in this mode, I no longer felt a longing to embrace a browser-based authoring tool to return online, because it wasn’t the tool that needed to be online — it was me.

Related Posts

11 thoughts on “Moving Between the Agora and the Desert”

  1. Ellis Pratt

    I think what is happening is that “social norms” (“social proof”) are influencing people.

    If you get feedback on what everyone else is doing (social proof) through the comments and dialogue, then that’s going to be very attractive to people. If you have the opportunity to be listened to (= you have an identity), then it’s even more compelling.

    Can’t you add the ability to comment at the bottom of each Help page?

    1. Tom Johnson Post author

      Thanks for your comment, Ellis. Re adding comments at the bottom of each help page, you can’t do that in Flare unless you have Feedback Server. I’m guessing future versions may provide more social tools, but not at the moment. At any rate, I’m not sure if I want comments below each help topic. It requires a lot of support to respond to comments. I’d rather direct people to the forums for questions.

    2. Paul Pehrson

      I think that one problem with comments at the bottom of help topics is keeping the comments on the topic of the help system. It seems that users often want to rant about perceived missing features, or functionality that doesn’t work like they expect, or some other comment not directly related to the help topic itself.

      If people used comments to specifically talk about the help topic, and provide useful information that is relevant or might be helpful, then that would be a good thing.

      I have watched people leaving comments even on MadCap’s knowledge base (integrated with Feedback server), and it seems that almost universally the comments are really support requests, not feedback on the documentation.

      If you want social commenting on documentation, how do you keep it on-topic so that the comment thread is useful to other users who come after?

      1. Jeff Coatsworth

        Paul, I think it comes down to moderating – which then circles back to what Tom was saying about it takes a lot of support to respond to comments. It usually is a matter of resources – most of us don’t have the time to stay on top of what needs to be added to our help, let alone ride herd on a bunch of thinly-disguised support requests.

        1. Paul Pehrson

          I wonder if it doesn’t boil down to providing a comments form, but including information that specifically states that the comments will be read but not responded to, and providing a link for Support resources. In this case, all comments would be sent back to the doc team, but they don’t need to respond to the individual questions, but can take them in aggregate to make changes to the docs.

      2. Tom Johnson Post author

        My experience matches Paul’s. When users see a comment form, they use it for support purposes covering a variety of topics. It turns the tech writer into a part-time support person (or full-time, if there are a lot of questions). If you don’t respond to the comments, it looks bad. If you do respond, it sucks up all your time.

        If you can leverage the comments to guide your documentation efforts (which you should of course do), then comments can be a big help. But unless you’re able to stay on top of it all, you might have a better experience by routing users to a common forum where other people besides the technical writer can respond.

  2. Mark Baker

    People will take the path of least resistance. They profoundly do not care about your organizational schema, so if you give them a place to type, they will type what they want to type and press enter. The question is, what do you do with that comment once you have it?

    You do not have to preserve their comment in the place they typed it. Just because the comment was typed into a form on a help page does not mean it has to be married to that help page.

    What you could do (if you have the appropriate structure and metadata in place) is to take that comment and insert it into a new forum thread. (Obviously, you need to show the author clearly that this is what you have done, so they know where to find it and where to look for updates, though they should be informed of updates by email, just like any forum.)

    Conversely, if there is a forum thread that develops on a topic related to a help topic, that forum tread should be made visible in some way to a user viewing the help topic.

    This is really a case in point of what I was talking about in http://everypageispageone.com/2012/12/03/time-for-content-management-to-come-out-of-the-closet/. We have to get past the notion that content simply exists where the author places it. Content should appear where it is relevant, regardless of where the author created it. We just have to get past the idea that content is organized by authors by hand. We have to start seeing it as something that is organized by algorithms based on metadata.

  4. Ferg

    One of the most effective ways I’ve found to immerse yourself in user feedback is to monitor your product’s support queue. In some cases, that may be an online discussion forum. In many cases, the organization will have a support team that takes calls from customers who are having problems. Reviewing those support tickets can help identify problem areas that you may be able to help address with help content.

  5. Roger Sharp

    Tom, great article. So are the comments. Forums, user feedback in Help, and wikis all have issues of time, moderation, iffy suggestions & guesses, ineffective search engines, off topic comments, etc.. Service/Support Depts are a great source of direct user needs and, hopefully, Service-supplied solutions. (As a lone writer I tend to rely on the Service Dept first.) Getting any valuable user feedback into the original Help, as you suggest, seems ideal. If there is a way to partially automate this, even better.

    As a user, I always check the Help first (static or not). They have the most authority and it is the quickest. Then if I must, I travel into the agora. It’s just like when I need a spigot washer, I go to the fastest source first. I first go to the corner HW store; if they don’t have it, I go to Home Depot or Lowes, then online to the spigot manufacturer.
    Just because most people go to the big boxes first (i.e., social norms) won’t stop me from going to the fastest, easiest, most authoratative source first, even tho I do end up getting a lot of answers from forums (ooh the pounding).

Comments are closed.