Diverging Directions for Tech Comm: Social Media or Structured Authoring

Two powerful trends in tech comm seem to be moving in different directions: social media and structured authoring.

I have used a wiki as my primary format for documentation for the past year and a half. I tried to corral a group of volunteer technical writers to edit and update the wiki, because I embraced the idea that collective intelligence beats the individual thinker in the long run. But even the most advanced wikis don’t have a structured authoring backend. With wikis, you compromise single sourcing, content re-use, and multi-channel publishing. So you really can’t move in both directions well. I feel like I’ve had to choose whether I’ll pursue structured authoring or social media formats for my help content.

While at the STC Summit, I kept thinking about metadata and the idea of sorting content semantically by queries that leverage the metadata. I asked more than a dozen of the smartest people in tech comm about this, and I came to the conclusion that if I ever wanted to do it, I’d need to embrace an XML format and develop custom semantic tags.

One evening I had a dinner conversation with Sarah O’Keefe about moving to XML. Sarah explained different ways to write XML and how to query the XML even when it’s not structured as it should be. She grabbed a napkin and drew the following:

The picture Sarah drew for me

The code Sarah drew for me on a napkin.

Yes, I kept this napkin! It was the best souvenir from the STC Summit. It’s funny because when she asked for an example of one of the metadata values and properties I wanted to use, I said role as the value, with editor as the property. But I must have mumbled it, because she wrote “elder” as the property instead.

After the conference ended and I returned to work, I decided to abandon my wiki and move all my content into our Mark Logic database, which stores content in XML. This is LDS.org’s backend anyway.  To do this, I would need to convert all my wiki topics into XML and add the appropriate metadata to run all the custom queries and provide the faceted filtering I wanted.

I spent several weeks coming up with the right metadata and applying it to all my topics. I was basically saying goodbye to Mediawiki and the idea of collaboration. I would structure my content in XML, and I would be the sole author. Not that many community volunteers edited the wiki anyway, but there was always the possibility that some day it might take off. Still, I had given the wiki almost 2 years without seeing fruit. It was time to try something else.

When it finally came down to the time when I needed to convert my content, I learned that the web development team had created special help templates for me. These templates included a WYSIWYG editor where I would basically create pages. Further, I wouldn’t even be the one converting the content. A special web development team would handle it all, populating the templates and creating pages, and even if I wanted to touch the content I could not. They planned to pull it directly from the wiki.

What about all of those metadata fields that I had labored over? I had to pitch the whole idea about semantic structure and findability again. In the end, they penciled in a future task in a later sprint to expose certain metadata fields in the templates for the web publishing team to use. The custom queries will be a future request, once my content is in XML.

I thought I would be swimming in XML and coding until my eyes turned blue, but it turns out that this approach is even less techie than the wiki. For the time being, I relinquished my publishing control.

I’m eager to see if the new format yields higher visibility and findability for the help. It probably won’t be until the end of summer when I can evaluate whether the migration from wiki to XML was a good idea.

In the meantime, I have not altogether abandoned the idea of collaboration. I’m a project lead for a community LDSTech project that is more community-sourced than my wiki ever was. I have more than a handful of writers creating and submitting articles.

But hoping someone will land on a help page, realize its a wiki, log in and make intelligent updates is a dream that only few groups have ever achieved (most visibly, Wikipedia). The promises and potential of structured authoring, with faceted filtering, semantic structures, and intelligent queries, seems to outweigh the attempt to collaborate efforts across large groups using wikis.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • http://kaiweber.wordpress.com/ Kai

    Tom, to quote Ann Rockley in her reply to the previous post in the series: “I don’t think that topic-based writing and end-to-end scenarios are mutually exclusive” – and neither are social media and structured authoring.

    It’s just that the type of content your users can and will generate differs, depending on your audience and content. The reason why Wikipedia excels where documentation wikis fail is that there are more users who can and will write reasonably good dictionary entries than can be said for documentation. It’s also often easier for users to create or find the right heading under which to contribute in Wikipedia; as we know from structured authoring, writing good, consistent headings is a skill in itself.

    But that shouldn’t stop you from engaging users in your documentation whether it’s in comments, forums, etc. So I don’t think you need to give up on social media in documentation, just because your wiki didn’t pan out.

    • http://idratherbewriting.com Tom Johnson

      Thanks for your comment, Kai. You’re right that there are other forms of social media to look to, rather than just wikis. I probably shouldn’t have equated social media with wikis in this post, since social media is much broader.

      I’m just trying to highlight two trends that seem to be going in opposite directions. By nature, most social media is pretty much unstructured, meaning it doesn’t conform to a specific XML schema. The XML trends have a very specific format to follow, which is beyond the skill level of the average end-user to adapt to.

      I haven’t had success on the wiki end enough to forego the benefits of structured authoring, so I’m trying the structured authoring route for a while.

      • http://kaiweber.wordpress.com/ Kai

        Tom, I agree: We tech comm’ers can’t expect any but the most masochistic users to follow our XML schemas… :-)

        But I was reminded of something when you said (I’m paraphrasing): “Ehh, the wiki didn’t do it, I’ll try structure for a while.” Three years ago, I read a great book that helped me get a grip on what works in social media and why. Charlene Li’s “Groundswell” takes it all apart and puts it back together again, so you can gauge your chances for success at the outset.

        One important strategy that Li presents is to put people before objectives before strategy before tools. Once you’ve figured out who your users are and what interest and skills they have, take the time to decide just how you want to relate to them and how you want to engage them. The tool doesn’t even come in until way at the end.

        Check out my blog post for a more thorough summary at http://kaiweber.wordpress.com/2008/06/30/top-6-ways-technical-communicators-can-benefit-from-the-groundswell/

        • http://idratherbewriting.com Tom Johnson

          Kai, thanks for pointing out Groundswell. I haven’t read that yet but should. I know that problems are often people problems, not tool problems. Getting people to contribute is an art, I know.

          • http://kaiweber.wordpress.com/ Kai

            > I know that problems are often people problems, not tool problems.

            That was not quite my point: I learned from Li that we need to think about people first (in sequence), then we decide what kind of relationship we want to have with them and what we can realistically expect them to do. And only then we look for the tool to help us get there. We’ve got to overcome the seduction of the tools!

            > Getting people to contribute is an art, I know.

            If your success in documentation depends on your idea of people behaving a certain way (as opposed to empirical studies of their behavior), you might just set yourself up for failure…

  • http://learningbywrote.com Don Day

    I see collaboration as a layered effort. I’m most keen on original contribution of new content from subject matter experts. Others may not join in on that task because the captured knowledge is unique to that contributor. This must be how many new topics originate on Wikepedia–someone cares enough to start the topic, and what they’ve written is definitive enough to stand as is. When the subject is more of a collective memory exercise, then you might see more individual contribution to the page. And how you validate and include such user-contributed knowledge into approval-managed pubs is yet another level of tricky function.

    So in this sense, wikis and structured writing line up very well. The ideal wiki would offer templates or even topic-based markup with validating editors to leverage the benefits you expected: single sourcing, content re-use, and multi-channel publishing (and semantics-informed search to boot). To this, I’d add optional workflow and business rules management so that enterprises can warrant the information. I’m confident enough with the discussions I’ve had around my expeDITA proof of concept to see that these are absolutely achievable goals. To take it to the next level, I plan to work with Kristof Van Tomme’s “DITA for Drupal” project to bring the best of those ideas to the popular and robust Drupal platform. I’m excited to see what his team can bring into what we might call “the structured collaboration community!”

    • http://idratherbewriting.com Tom Johnson

      Don, I’ve been impressed with the prototype DITA-based wiki you started at Learning by Wrote. Is that what you mean by the expeDITA proof of concept?

      I’m excited to see the integration of DITA with Drupal. That would be a welcome addition to the web-based tech writing tools.

      I am eager to see a toolset evolve that will make structured authoring simpler and easier for SMEs to use. Content ownership for SMEs is a huge issue that we give up with structured authoring methods right now. I’ve never met a SME willing to use anything but Word or a wiki.

      • http://learningbywrote.com Don Day

        That’s the one, Tom. Fundamentally, Drupal provides all the back end and workflow functionality a team could need, and full-functioned commercial editors already exist for integrations, so many pieces of a solid system are already in place for wiki-like deployments. But to truly catch the “long tail” community of open source adopters at smaller organizations, there is still a need for a basic, open source, WYSIWYG web editor for DITA content. By aligning with the Drupal developers community, I am hopeful we can see something useful emerge soon.

  • http://ca.com patty blount

    Hi, Tom,

    When my team researched a wiki transition last year, we had the same questions. How can we reuse topics, especially given how literal Wikipedia is when creating [[links]], which is not the same as [[Links]] or worse, [[LInks]].

    Organization is another pain point for me.

    We have an internal wiki set up for collaboration but my first attempt at using it crashed and burned. My development team copied all the topics into a Word doc, turned on Track Changes and emailed it back to me.

    • http://idratherbewriting.com Tom Johnson

      I figured out how to do a lot of things on Mediawiki, including topic reuse. I ended up restructuring how I used Mediawiki. I broke up all the topics on my page into separate pages. Then I called them onto the page using {{:page name}}.

      It works, except that it makes it more difficult to edit the wiki. I started using and tags to make sense of it all. In the end, it just became a convenient publishing tool for me. I still love wikis, though. They make publishing so easy. But to take help to the next level and implement faceted filtering, it wasn’t possible, even with the Semantic Extension.

  • Linda O

    Did you know that the STC-TE SIG’s web pages are a wiki? I think they do get a bit of help from their viewers…not as successful as Wikipedia, but a good example of something we know.

    Thanks, Tom, for your continued expertise and communication about technical communication. You are one of the best we have!

    Linda O

    • http://idratherbewriting.com Tom Johnson

      Thanks Linda. Yes, I think they’re using Twiki. It’s great if they’re getting a lot of contributors. One of my problems is that I’m in an organization with a very top-down culture, and so wikis run against everyone’s comfort level to begin with.

      The real genius of wikis is not how simple they are. It’s figuring out how to get large groups of people to contribute.

      • http://prosekiln.com Melanie

        Excellent post. I’m considering this myself. We actually use TWiki (I checked the SIG’s website, and they use Tiki Wiki, another product).

        Thanks for the thoughts, Tom. Great to know others are thinking along the same lines.

  • http://www.sdicorp.com/Resources/Blog/articleType/AuthorView/authorID/24/lkunz.aspx Larry Kunz

    Richard Hamilton gave a good presentation at the STC Summit about how Alan Porter wrote his Wikis for Fun and Profit book for XML Press in XML using a wiki front-end. I don’t remember if Alan added semantic tagging to the XML while he was writing or afterward. But either way I recall that it was fairly easy.

    So, as Kai said, you don’t have to choose between social media and structured authoring. There’s a lot of demand for synthesizing the two, and the tools are evolving rapidly to meet the demand.

    • http://idratherbewriting.com Tom Johnson

      I attended Richard’s presentation. It was excellent. If you know enough about XML to write a custom transform to migrate content from HTML to XML, and then from XML to Docbook, and then to further output it to the various print formats using other transforms, great. I am not at that level. I really have not seem a social media/structured authoring solution that does not involve a lot of custom programming like that.

  • http://wikihelp.autodesk.com kandis

    Hi Tom,

    Autodesk has a wikihelp platform that we are using for a number of our products.

    We produce the content in XML/DITA using Xmetal and the Trisoft cms, and then output content to the wiki.

    Users are welcome to Edit/Edd/Comment on content, either in the Help that we provide, or in Community sections that are more free-form.

    We are still working on improving our tagging and SEO to improve findability but we don’t see this as stopping us from engaging with the community to keep the help alive after release.

    Thanks for your great blog!


    • http://idratherbewriting.com Tom Johnson

      I have been curious about strategies that use wikis as an output, rather than as an authoring platform. If that’s working for you, great. Out of curiosity, how many contributors edit your wiki? And then do you carefully track those edits and input them back into the source files?

      That seems like a workable solution — as long as you don’t get that many edits on the wiki. But if you don’t get that many edits, perhaps the wiki isn’t that essential?

  • http://everypageispageone.blogspot.com Mark Baker

    Hi Tom,

    I have to agree with many of the other comments. Structured writing and collaboration are not mutually exclusive. In fact I would go further and say that structured writing is essential to effective collaboration.

    Wiki’s are an interesting phenomenon. But it is inescapable that there is really only one great wiki success story: Wikipedia. Some groups have used closed wikis as an online authoring platform for their writing staff, but that has little to do with the original wiki philosophy of a shared and anonymous space in which anyone can add to any topic and where anonymous refactoring is considered an essential part of the method.

    Where the wiki philosophy breaks down is issue of permission. For wikis to work, people have to feel free to edit anything at any time, and they have to accept that whatever they write may be edited by others. Wikipedia succeeds because they manage to maintain that philosophy, with suitable controls to limit vandalism and propaganda, and a strict policy against original research. It is a remarkable achievement, and one that is hardly ever duplicated. Most wikis I have seen and worked with each page is “owned” by a individual, and no one feels at liberty to refactor other people’s pages, with the result that the wiki clogs with redundant and competing pages.

    Collaborative authoring depends on people feeling free to contribute, and that feeling does not come from a totally open environment, but from one in which people feel that they have permission to contribute through a specific channel, and that their contributions will not spoil the work of others. In this sense, blogs work far better than wikis for collaborative development of a subject, because each person’s comment is separated from the blog text and the comments of others. People feel they have permission to contribute, and that they contribution cannot inadvertently damage the contributions of others.

    Collaboration requires structure. It requires structure to provide permissions and safety for contributors. Beyond these basic necessities, structure can provide guidance and feedback to assist and assure contributors. Forms and highly-subject specific schema can provide the structure that enables collaboration.

    We make extensive use of very specific XML markup to capture information from developers. It works for them because they know exactly what is required of them, and they can avoid multiple rounds of emails and interviews with writers. It works for us because we can get information straight from the source in a form that we can process directly into end user content with only a little editing. The fact that the content is captures in a highly structured way is what makes it possible to integrate it effectively and safely into the overall doc set.

    Structure, in short, is not the antithesis of community authoring, but its foundation.

  • http://www.logoian.com/ Corporate Logo Design

    It’s really amazing article. It is always nice when you read some thing that is informative & interesting. Excellent work. Keep it up!