Moving Between the Agora and the Desert

by Tom Johnson on Dec 16, 2012
categories: findability • technical-writing • wikis • wordpress

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.

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.