1. Writing documentation in a wiki suits me for the same reasons I enjoy interacting on the web. The web is interactive, alive, dynamic, collaborative, fresh, and unlimited in potential. A wiki, being online, allows me to partake in the same game-like, community-rich environment that I thrive in.
2. It’s much better to focus on just a few key projects rather than spread myself too thin. I made the mistake of extending my reach into too many projects this year, sometimes taking them upon myself because the applications needed help. As a result, I wasn’t as informed as I usually am about the most important projects, and it showed. Later I pulled back and ignored everything but my two main projects, and I felt much better with this strategy.
3. I need to set goals to write at work. It’s astonishing how non-writing tasks can eat up the day. Lately I’ve set a goal to write for 4 hours a day at work. I rarely achieve this, though really this goal has caused me to reflect on what writing actually is. If I’m reviewing forum threads to detect issues to write about, or experimenting with a test system to determine steps for documenting a task, isn’t that writing? The typing part comes at the end and is fairly minimal. Regardless, just setting a timer on my iPhone prompts me to dig into the documentation topics and produce something tangible.
4. Content marketing, played out in the form of corporate blogging, is kind of boring. Corporate blogging isn’t what I thought it would be. Mostly the corporate scenario is stifled by lack of creativity and freedom to explore. You’re expected to toe the line, to avoid controversy, to vet each post through five levels of approval. Comments from readers are usually brief, unenlightening, and often don’t match the topic of the post. I find technical writing more engaging.
5. A centralized help authoring system is a neat idea, but I hate the lack of control. The idea with a centralized help authoring system is that you install the system on a server with all your styles defined in one central location; an administrator sets up everything to be a push-button publishing solution, and then everyone else just “focuses on content.” However, when you’re used to designing your own help solution, learning to rely on one (often remote) person is discomforting. I like having some control over the design, layout, style, and publication of my help material.
6. Community collaboration is extremely tough to pull off. I can’t just assign a volunteer writer a topic and let them run with it. I usually have to either gather the information from a subject matter expert or connect the volunteer with a subject matter expert — and then see them through the process with more hand-holding than I want to provide. Still, community volunteers can generate momentum by the sheer number of assignments I have to follow through with. Overall, I have no idea how to engage community volunteers in an effective way, but I think I can eventually figure a strategy out.
7. Sitting embedded with my project team is more effective than sitting with other technical writers. Sitting with my technical writing team, I end up collaborating a lot on standards, goals, styles, and other issues — which can be useful and important. However, the core substance a technical writer relies on is project-related information. No matter how many IRC meetings, scrums, iteration reviews, and other interactions, nothing replaces the information and rapport you get through proximity to the project team. However, proximity to the project team is just one element. Proximity to end-users is even more important. (See my post on The Proximity Problem for more analysis.)
8. Just because my job involves sitting at a desk all day with little movement, it doesn’t mean I’m fated to become a couch potato. By counting calories and following a whole-foods, mostly plant/fruit/grain diet, I can actually lose weight while improving my overall health. I’m not becoming a vegan or anything, but I had no idea how poor my eating habits were. The My Fitness Pal iPhone app gave me a wakeup call. The Forks Over Knives documentary on Netflix also made me question the integrity of the traditional food pyramid.
9. I’m not that interested in fiction. In the fall, I went through a fiction phase that lasted a good three months. During that time, I read and wrote more fiction than I have for the past 10 years. I eventually lost interest and realized I was more attracted to non-fiction for reasons I can’t entirely explain. I like the immersion in ideas (not that fiction is idea-less, but the ideas are shown rather than explained). I enjoy the sense of being “on top of the game” when I’m immersed in non-fiction (such as findability topics) and blogging about these same ideas. It infuses me with a lot of enthusiasm for my job, this blog, and my overall career.
10. Metadata is the most compelling strategy for findability, but I don’t know how to harness it yet. I experimented with the Semantic Mediawiki extension in a help system, and I liked the ability to tag and query topics in new ways, but I didn’t explore this strategy enough to be successful with it. I feel that I’ve only scratched the surface. There is so much more to discover. David Weinberger’s book Everything Is Miscellaneous, which explores metadata in depth, was the best book I read in 2011.

Based on what I’ve learned, as I go into 2012, I plan to do the following:

• Use Mediawiki more.
• Set goals to write more at work.
• Focus on fewer projects.
• Possibly hire an intern to help with the corporate blog.
• Leverage community volunteers for non-writing tasks.
• Eat smarter.
• Read more non-fiction books.
• Figure out metadata and findability.

Note: I do change my mind frequently, so no doubt this list will evolve as the months in 2012 pass by.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

I’m not a wiki fan myself — I’m a structured text guy bred in the bone — but I am fascinated by the trend, and by the variety reactions to it.

Wikis started more as a cultural statement than a technology. They were a tool for the democratization of content, the intent being to eliminate the distinction between reader and writer. In the wiki philosophy, every reader was also a writer, there was no ownership of content, and not notion of a final, finished, of blessed editions of content. The wiki was always open, always evolving, and blessed only by the consensus of the community. Today, it would style itself “occupy content”.

What wikis have become, largely, is an unstructured CMS with only one face. A traditional CMS has two faces: one toward the author, and one toward the reader. A wiki has only one: the same face toward reader and writer, with every page having an edit button on it. Except that today the edit button is locked or hidden from most users. The distinction between reader and writer has been reintroduced and enforced. The original wiki philosophy has been rejected.

Still, the stated motive of most people who adopt wikis for technical communication is to allow more collaboration and to open up authoring to a wider community. So some shadow of the wiki philosophy is still at work. That being the case, I think there are a couple of things that people need to understand about the wiki philosophy and its consequences.

The first is, if you want to crowdsource effectively, you need to be open. People need gratification. If the content they contribute disappears into a black hole of moderation and curation, they don’t get the immediate gratification of seeing their work published, and gratification delayed is gratification denied. You won’t get a lot of content from the crowd unless you let the crowd publish.

The second is a consequence of the first. The implication of the idea that there is no distinction between reader and writer is that the reader has to take more responsibility for what they read. The old contract between the writer and reader of technical content, that the published content had been vetted and could be relied upon uncritically, cannot be sustained in a crowd-sourced world. The reader of a wiki, like the reader of any Internet content, has to assume some responsibility for vetting the content they receive.

By and large, readers do understand this. It is the responsibility they accept every time they type something in a Google search box. The simple fact of the matter is that readers prefer unblessed content that addresses their task and is available now over blessed content that does not cover their task or will not be available until next year. Timeliness and coverage trump all other considerations most (thought definitely not all) of the time.

The question for tech writers is, is there a place in your hearts, and in your company’s relationship with its customers, for unblessed content that enhances coverage and timeliness?

I like Mark’s comment for several reasons. He brings up several key points with wikis:

• “[Wikis] eliminate the distinction between reader and writer.”
• “Readers prefer unblessed content that addresses their task and is available now over blessed content that does not cover their task or will not be available until next year.”
• “People need gratification. If the content they contribute disappears into a black hole of moderation and curation, they don’t get the immediate gratification of seeing their work published.”
• “The old contract between the writer and reader of technical content, that the published content had been vetted and could be relied upon uncritically, cannot be sustained in a crowd-sourced world.”

When we talk about wikis, it’s important to see them as more than just another authoring platform. As a reader, knowing that I can change the text alters my sense of the text. It is no longer the absolute word on the matter. I can be a part of the conversation; I can change the message. It is my content as much as another’s.

And making those changes immediately, seeing it published instantly, is gratifying. It’s empowering, almost to the level that the printing press changed the distribution of knowledge. Wikis take it to another level, allowing every reader to also be a publisher. Tapping into the knowledge that every reader has, inviting the reader to share that knowledge, and trusting the reader that he or she will shape the content responsibly, isn’t just a shift to another tool. It’s an entirely different way of thinking and interacting. It’s the 21st century interactive read/write web model. It’s a model that acknowledges that the sponsoring organization doesn’t have all the knowledge, but that individuals located in disparate regions also have important contributions to make — and that they should share those contributions. Wikis democratize the knowledge landscape, allowing everyone to speak without pre-filtering editorial control.

This is why, like Mark, I am also fascinated by wikis. In an organization like mine that is traditionally top-down, with careful filters on outgoing messages, a wiki is a complete anomaly. And yet, it is also not an anomaly. Latter-day saints have a history of volunteering, of consecrating their efforts for the community. In the nineteenth century, members would contribute their time, talents, and own funds to build temples (which took years), or to work in fields. In this sense, a wiki is a perfect fit. It is a knowledge project rather than a physical structure project.

Mark also brought up the fact that he is a “structured text guy bred in the bone.” I was talking with Scott Abel last week, and as Scott was explaining something about structured authoring, I brought up this question: Don’t you see wikis and social media as going in the opposite direction of structured authoring?

I know we need to put our content into structured forms so that it can be leveraged into other channels we need to publish to (ePub, mobile, web, print, and more). But it’s impractical to ask people in the community — who are not technical writers and who do not have your same toolset and knowledge — to write in structured formats. Taking contributions from the masses requires you to simplify your authoring model. You end up with an either/or choice. Either you can go the structured authoring route, or you can go the social collaboration route.

In response, Scott mentioned a point similar to what Mark says about content management systems. The only thing that really separates a wiki from a content management system is that the content management system hides the Edit button from the user. If I were to give you login information for my WordPress blog, for example, you would see an Edit link below the post title. You could log in and make changes to what I’m typing right now. With one flip of the switch, I could simply convert this WordPress content management system into a wiki-like platform, breaking down the division between reader and writer, and accomplishing the same end. Right?

What’s more, if the content management system stores content in XML, or relies on some other structured authoring interface for writing content (you can export from WordPress to DITA, for example), it would solve the problem that I describe above about the divergence of structured authoring and social media. Right?

Sort of. I would like to see more content management systems move in this direction. I’m not that familiar with all the various content management systems out there and the number of wiki-like interfaces they potentially offer. In my experience, many times the content management system is behind a firewall or has other security restrictions. Many content management systems may not provide the inviting simplicity that traditional wikis offer. And licensing is also another issue. As a result, more often than not, users cannot simply click an Edit link and start updating content.  However, I think that it’s only a matter of time before this becomes more normal.

What do you think? Do you agree with Mark’s observations about wikis? Are socially collaborative tools and structured authoring going in different directions?

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

It’s not because I’m lazy. I’ve actually become somewhat of a workaholic, working on weekends, sometimes a little in the evenings. The problem is that there simply aren’t enough technical writing resources for the work we do.

This situation was taxing my patience, and I started to think of the immediate solution: hire more people. I already mentioned that we have one opening. This is just back-filling a position from a writer who left. But we need about half a dozen more writers, in my opinion, to do a good job. I thought about trying to hire interns, or trying to recruit full-time volunteers.

While I thought of these staffing solutions, I also thought of other things I have heard our leaders say. We have to find a way to meet the demands of a growing membership without commensurately staffing up, some said. And another: If you set your goals higher than you can achieve, you will change your methods in a way that allows you to achieve them.

While I liked these ideas, I didn’t have a clear idea of how to move toward them. I was constantly working in crisis mode, trying to cross off the top three items from an ever-growing list of tasks each day.

As if the documentation challenges weren’t enough, I had also taken it upon myself to do marketing for technology products across departments. I fished for tech news information in every corner I could find– forums, RSS feeds, intranet content, email lists — and then worked with volunteer writers and subject matter experts to get the articles written. I greased the approval system, learning how to navigate the large number of checkpoints with skill and prowess.

Despite some successes, I realized I couldn’t move in two directions at once, both playing documentation and marketing roles for so many products. I needed a way to scale without  simply growing our team with more full-time resources.

A Glimpse of the Solution

Just last week, I felt like I caught a glimpse of the solution. I have a group of 60+ volunteer writers eager to help out. (I wrote about the challenges of managing volunteers last week.) In fact, there are hundreds of church members (as well as non-members) out there who are eager to serve and volunteer for LDS Church writing projects (I work for the LDS Church). I hadn’t  leveraged their efforts except for the marketing side of tech, writing articles for the blog about new releases, updates, and other technology topics. I didn’t have them creating documentation because I saw these as separate efforts.

And then it hit me: These aren’t separate efforts. Good documentation about new sites, tools, and resources can be used for marketing efforts. Marketing and documentation don’t need to be separate efforts. I could leverage volunteer enthusiasm for documentation and then pull highlights from the documentation to post as news for the blog.

And what platform would allow 60+ volunteers to contribute writing and editing? The traditional help authoring system we were using didn’t seem adequate. The cost per license and lack of availability outside the firewall made it impractical as a collaborative volunteer platform. About the only platform that works in this situation is a wiki.

One of my colleagues explained that volunteers could write in Word templates and then send me those templates. I could then import the templates into the help authoring system and generate help material from it. This was a system he had used in the past for internal SMEs who wrote content. While this could work, he acknowledged that the process would be somewhat impractical.

One of the problems is that we don’t have a set of number of official products we document. If you look at this list of categories on LDSTech, our users have questions that span across products, departments, and roles. There are dozens of different topics, sites, tools, resources, applications, processes, methods, issues, and other areas that users have technical questions about. Would I create a new project to publish information about each one? The most feasible platform to accommodate such an information ecosystem is a wiki.

Pros and Cons of Wikis

I have to say that, in general, I really like wikis, especially Mediawiki. Wikis have so many advantages that it’s hard for me to understand the case for traditional help authoring systems when you need a collaborative authoring environment. Here are the main advantages I see with wikis in my authoring situation:

• Wikis scale infinitely. Mediawiki is actually free, and it supports an infinite number of users. You don’t have to shell out $1,500 per license. People can just log in and start authoring. It scales to support a growing user base.
• Wikis remove authoring complexity. Some help authoring tools require a lot of tinkering before they make sense to users. In contrast, adding content to a wiki is fairly straightforward. It’s a matter of asterisks and pound signs and equal signs, for the most part. There is some syntax to learn, but it’s nothing prohibitive. This is essential to expand the base of authors.
• Wikis allow collaborative authoring. When you have multiple people working on the same content, nothing is easier than a wiki to facilitate this collaboration. Mediawiki even allows more than one person to work on the same page at once, and is smart enough to handle simultaneous commits of the same sections.

I mentioned that I’ve tried using wikis before. Some of the reasons I abandoned it previously include the following:

• Wikis don’t allow you to single source the content.
• Wikis are poor at translation.
• Wikis don’t get enough edits from users to justify the platform.

I want to address some of these objections, if only to provide notes for myself.

Although many people don’t realize it, content re-use in Mediawiki works much the same way as it does with help authoring tools. If you put content in a template, you can re-use that template in any other page as much as you want (it’s called transclusion with Mediawiki). You can also embed pages inside of other pages.

What you can’t do is easily push the content to a nicely printed manual or do other multi-channel publishing (at least not with Mediawiki). You could, however, come close by embedding pages in a specific order and then customizing the print CSS stylesheet. But in all the feedback I’ve seen on forums and through email, I have yet to come across a request for a printed manual. I do often create one-page quick reference guides that people can print. These seem to satisfy the need for a print experience of documentation.

With translation, while help authoring tools may package up all the essential files and make it easy to export and reimport those files, I don’t think wikis are impractical for translation. Look at Wikipedia, after all. How is it available in so many languages if wikis aren’t suitable for translation? What’s more, wikis allow for community translation in a way that help authoring tools usually do not. Many people from the community can work on translating pages, and they can translate as much or as little content as they want.

Finally, as for the argument that wikis are underused, I think this is because people misunderstand volunteer dynamics. Just adding an Edit button on a page doesn’t mean people are going to edit the content in useful ways. In the same way, if you walk into a room of people and issue a blanket call for volunteers to work on cleaning up the roadside, not many will do it.

Managing volunteers is all about relationships and personal invitations. If you have a group of people who have volunteered to do writing, and you invite them to do specific writing tasks, they do it more often than not. Getting people to participate requires management. It requires some relationship building and follow-up. But it’s possible, and the effects can be somewhat staggering.

I don’t mean to discuss the merits of wikis at length here. Certainly wikis have shortcomings. For example, with Mediawiki, the access model seems a bit narrow-minded to me. You can’t control access at the page level; everything is either open or closed. Skinning themes is also more complicated than it needs to be. But it’s a platform that has many more advantages than disadvantages. And the success of Wikipedia seems to trump all possible arguments against the viability of wikis or Mediawiki as a tool for knowledge.

Conclusion

It’s too early to tell whether moving back to wikis will solve the resource problems I mentioned earlier. But I’m hoping that I will have learned enough about engaging volunteers to make wikis finally work for me.

I know wikis aren’t ideal for every situation. If collaboration isn’t important, if you aren’t stretched thin with resources already, and if your internal technical writing team can adequately handle all the documentation needs, can cover all the various perspectives, issues, scenarios, and other topics that your audience wants to see addressed, then a traditional help authoring tool would be a good fit.

But in my experience, the need for documentation is only growing. The idea that a single writer can adequately provide instruction for a system that thousands of people use — people in different roles, environments, locations, perspectives, and business contexts — is an idea that falls short for me time and again. When I sort through feedback and forum threads, my eyes are open to all the gaps and unanswered questions in my documentation.

Collaboration and interaction are key characteristics of the web for a reason: when you allow others to contribute information, the value of the information grows. It becomes more accurate, more comprehensive, and for those who contribute, the documentation becomes their own. This sense of ownership is perhaps the most powerful effect of a collaborative platform. When your users feel ownership about the documentation, they are more inclined to tend and care for it in the long term. In contrast, internal technical writers often move on to another project after one finishes.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

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 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.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

While some credit is certainly due to Google’s Pagerank algorithm, what enables findability in Google is that there’s so much content on the web to find. If you have billions of web pages, of course the search engine is going to come up with results that match almost any keywords you enter. As a result, because of the mass of content, you have instant findability. Take away the content, leave only the algorithm, and you have nothing.

Above: You find information on Google because it draws upon a wide variety of content authors for the information. Below: A typical help file lacks information because usually only one person creates content for it.

How much of that content is Google generating itself? Almost none of it. The web is like a giant wiki, where anyone can author and publish content. Only instead of adding new wiki pages, we’re all adding our own sites and pages on our sites.

I brought this up as a colleague and I were discussing our organization’s external wiki, tech.lds.org. It’s a wiki that has quietly been growing in size each day, used for myriad purposes both internally and externally. You can do a search on quite a few topics and pull up content — because so many people are authoring. There are probably more than 20 regular authors contributing to that site, with probably 30+ daily edits. When you have so many authors producing content, the result is that someone is going to address a problem that another is searching for. The answers are findable.

The paradigm of a single author controlling all the content for a knowledge domain — keeping it in a tightly structured environment that moves through a strict editorial process — is a model that, no matter how well organized or planned out, will probably fail when it comes to findability precisely because you only have one person creating the content. That one person is inevitably trapped by his or her own experiences, by his or her limited domain and restricted viewpoint, by his or her job role and title. There’s no way a single person can produce the mass of content necessary to enable findability on a wide scale. The person will produce 100 single-focused pages compared to the 10,000 multi-faceted pages produced by an army of authors.

The intelligence of the web isn’t the technical infrastructure or the idea of bandwidth or CSS. Its intelligence comes because so many people contribute content. It’s the true global encyclopedia — Wikipedia is just one part of a larger body of reference information. We’re all contributing to it, page by page.

We’re only about 15 years into this endeavor. Imagine the size of the content repository in 50 years. We’re moving towards a book of knowledge that is growing daily, becoming more and more comprehensive — and it’s because of the individual contributions, not because of a specific authoring tool or process or technology.

It’s a free for all, sure, with any kind of design, format, and style. But despite the variances, people look past design and focus on content. This is why, when we consider enterprise authoring methodologies, what makes the most sense is the authoring methodology that empowers the most people to author.

As more people author, the pool of content grows wider and deeper. Soon you’ll amass enough information that, although it’s a content dumpyard in many cases, when users dig around they find the nuggets of information they’re looking for. It’s not a huge problem if the individual content on each page or project varies in layout, color, and style. The mere fact that the content is there, because you empowered a subject matter expert or user to author it, means that you have content. Content exists. This content gives rise to findability.

Although I have looked at many authoring tools, I think the one that triumps them all is the wiki, precisely because it enables the enterprise to author content. Many times the authoring is stifled and only a fraction of what it could be, but other times large numbers of contributors jump in and author. They produce loads of content. When this happens, the result is something far greater than any single authoring team alone can produce.

In short, findability isn’t enabled by some clever organizational technique such as tagging or faceted browsing or even schema theory. Findability is enabled by empowering all humans to share and publish their knowledge.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Wiki: Grow your Own for Fun and Profit, by Alan Porter

Alan Porter’s Wiki: Grow Your Own for Fun and Profit, published by XML Press in October 2010, provides an excellent introduction to wikis. This is a short, easy-to-read book spanning about 150 pages. Alan has a keen sense of organization and liveliness in his writing. He carries the gardening metaphor throughout the book, ending with five solid case studies and an extended response to common criticisms against wikis.

Sometimes discussions about wikis make it seem as if they’re a new technology. But Alan explains that Ward Cunningham developed the first wiki in 1995 — fifteen years ago! Despite the relative ease with which Alan responds to wiki concerns (about inaccuracies, lack of participation, disorganization, and so on), wikis still haven’t gained traction as the predominant authoring platform.

One has to wonder, given the many advantages of wikis, why they haven’t they taken off as the platform for web and help content? Especially in an age of collaborative authoring, distributed ownership, dynamic editing, and agile development, you’d think wikis would be the most common platform for help authoring in tech comm departments.

And yet, in the 2010 WritersUA Tools Survey, wikis aren’t even included as a tool (see the survey’s list of tools). Almost every other help authoring, graphics, and video, and layout tool is mentioned, but wikis are absent. Either WritersUA accidentally omitted them (this year and every previous year), or they don’t take wikis seriously, or wikis aren’t considered help authoring tools.

My point is that wikis still have a long way to go toward mainstream adoption, despite their decade-and-a-half presence on the web. Alan’s book is a welcome addition to the promotion of wikis and wiki culture.

Although Alan’s audience seems more focused on new wiki users, he does dive into an issue that I struggle with: wiki round tripping. With round tripping, you publish from a source format to a wiki format, allow the wiki to be updated, and then write your updated wiki content back to your source format. For example, with WebWorks, Alan says the original documentation source is in Framemaker, which they publish to a wiki format using ePublisher. If they did round-tripping, after the wiki was updated, they would write the updated wiki content back to Framemaker.

However, WebWorks doesn’t do round tripping. After users make edits to the WebWorks documentation, the WebWorks team manually updates the source Framemaker files with the changed content.

Even if they wanted to do round-tripping, it isn’t easy to achieve technically. And I assume the technical solution isn’t available because apparently there isn’t a business case for it.  Alan says,

When I hear people using the phrase ’round-tripping’ they tend to be talking in terms of automating the process. When I have asked people what the business case is for implementing automated round-tripping, very few have an answer beyond “well it would be cool.

Alan notes that with a multilingual wiki, there may be a valid business case. But for most corporate content, round-tripping may pose liability or legal issues, and requires human intervention to evaluate whether the updated wiki content should change the source file. If round tripping is necessary, Alan recommends making the wiki the original source.

This section was most relevant to me for several reasons. First, round-tripping is very much a tech comm topic rather than a general wiki topic. Second, Alan gets into a difficult issue and explores it in depth. And third, there is no easy answer.

In the authoring process for some of my projects, we do keep the wiki as the original source, rather than maintaining a separate source of content. We all collaborate through the wiki, building the documentation as we go. In my opinion, working in Framemaker and then publishing to the wiki (the WebWorks model) undercuts the collaborative nature and power of wikis. If you’re the only one creating the documentation, it might make sense. But in a collaborative authoring model, with a team of internal and external authors, why create documentation in Framemaker first and then publish it to the wiki? How exactly would you share the content? Also, if community momentum picks up, how can you feasibly input the community’s constant updates back into the source files?

However, if you do use a wiki as the original source, you run into a problem: how do you selectively package up the wiki content and output its content into printable formats? How do you personalize the topics based on specific roles?

These latter questions might be related more to the wiki tool rather than wikis in general. Some wikis allow you to bundle the content together as a PDF output, while other platforms require extensions and hacks to achieve this. Access control also varies widely among wikis. Confluence offers different access control levels, while Mediawiki has an everything-open or everything-closed policy.

Alan’s book makes me reflect more about wikis. Will they ever take off? What holds them back? Is it the lack of a universal wiki syntax? Is it because wikis all too often devolve into chaos? Is it because the fundamental idea of volunteer group writing is flawed? I’m not sure. I prefer wikis more than traditional help authoring tools, but wikis still pose many challenges. I’m glad Alan took the time to write a book on wikis. It will help push tech comm authoring models more toward wikis.

For a sample chapter and links to buy Wiki: Grow Your Own for Fun and Profit, see the XML Press site book page. To read Alan Porter’s blog, The Content Pool, go to http://4jsgroup.blogspot.com.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

I used to think the site was a hodgepodge of software platforms, but now I see that these three resources can harmonize together in an amazing way.

A possible workflow of information from forum to wiki to blog.

Here’s the interaction in a little more detail:

• Forum: Users contribute openly and regularly to the forum, creating at least several new threads and probably 15 new responses a day. Users feel comfortable posting and responding to forum questions, because they aren’t making official remarks about any topic. They’re offering their thoughts, or asking questions. It’s an informal medium that is inviting and comfortable.
• Wiki: The conversations on the forum drive needs in the wiki. Answers and resolutions from the most popular forum threads should be transferred to the wiki as official articles.  Transferring this content requires you to organize and articulate the information, which isn’t always easy. So admittedly this transfer isn’t often done with the site I mentioned, but if someone were designated into this role, it could be powerful.
• Blog: The blog showcases the information recently added to the wiki. The blog can also serve as a voice to energize a community, to call attention to needs on the wiki, or to bring other news to users.

I never considered how well these tools work together, but they do. The different mediums allow users to interact in ways that suit them. Of course it would be nice to have one tool that has an incredibly powerful blog, wiki, and forum wrapped up into one package. Some wiki platforms provide all three, such as Tiki Wiki. But swiss-army knife tools almost invariably perform much like an on/off road motorcycle.

The drawback of having three sources for content, however, is that content published on one source may never make it to the other sources. For example, if I write a blog article about a new application, shouldn’t that content also appear as an article on the wiki? If a forum thread clarifies a topic, shouldn’t that clarification be added to a wiki article? If I add a new wiki section, shouldn’t that section be announced and summarized, as well as explained, on the blog? Content overlap becomes a problem. So does search.

Regardless of the overlap problem, combining a forum with a wiki and blog has tangible benefits. It helps solve the participation problem with wikis. Users are more comfortable asking a question in a forum rather than changing the original content of an article. Wiki admins can harvest information from these forum threads to strengthen the information of the wiki. Significant new wiki information should be announced to users on the blog.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

I also noted that wikis are probably the most suitable web platform for help authoring. However, wikis pose challenges with content organization because they usually lack a table of contents feature, and the link-based model of connecting pages makes the navigation maze-like and confusing.

Categories are one way to organize content on Mediawiki (the wiki platform I’m examining). Categories on Mediawiki work similar to categories on WordPress: when you add a category label to a page, clicking that category label shows all other pages labeled with that same category. You can have categories and subcategories and sub-subcategories, if you want.

Categories have their limitations. Simply tagging a page with a category throws the category into a list, with all category items usually arranged alphabetically. If you have hundreds of topics, forcing the user to dig around in lists of category pages will prove to be a frustrating experience. You need another way to organize wiki content for users.

Templates to the Rescue

Fortunately, with Mediawiki, you have more options for organizing your content than by simply adding category labels. Mediawiki also provides you the ability to create templates. Using templates, you can provide a navigation system that functions more similar to a table of contents.

By table of contents, I’m not referring to the auto-generated table of contents that points to headers on the page you’re viewing. I’m referring to a separate navigation system that pulls together multiple pages and presents them as links at the top or side of the page.

For an example, see the documentation I wrote about Joomla on LDSTech. In the upper-right corner is a template that functions as a navigation system for a group of pages.

Example of a template acting as a table of contents for a group of wiki pages

How to Create Templates

In Mediawiki, you create a template by adding [[template:swordfish]] on a page (in this case, swordfish is the name of the template I’m creating). You then add the custom set of links you want to include in that template page. To embed the template on your page, simply type {{template:swordfish}} where you want the template to appear.

The template navigation usually consists of links (styled however you want) pointing to your other wiki pages. Mediawiki is smart enough to dynamically change the class of the link that corresponds to the same page you’re viewing (the class becomes “selflink”), so you can create a unique style for the selflink class in your stylesheet.

What’s cool is that you can have a separate navigation template for each grouping of pages on your wiki. Typically wikis grow to monumental sizes, with hundreds or thousands of pages. Your documentation on the wiki may only occupy 15 pages of the wiki, but you often need a way to keep these 15 pages closely grouped together, to provide a navigation system for just these 15 pages. Templates provide a perfect way of doing this. And unlike categories, you can order the links on the template into whatever arrangement you want. (Category pages are by default arranged alphabetically in a table unless you use a special sort key.)

Note: You can use templates for a wide variety of purposes, even for single sourcing your content. I am just using a template in this instance for a navigation system. Templates are more commonly used to insert notes and other commonly used boilerplate material.

An Example

At my organization, we’re working on a new version of lds.org, which you can see at http://beta.lds.org. This skin has a side navigation system when you drill into the pages, such as this one. I created a Mediawiki skin with a template that acts as a side navigation system, just like the original site. In my template file, I added an embedded style at the top, calling it “sidenav”. I then styled sidenav to appear on the side rather than in the main content window.

Here’s a screenshot (with the text replaced):

My template-based navigation system in Mediawiki

For the most part, the template navigation system works well. It provides an easy way to navigate a group of pages on the wiki. Each page can have multiple topics on the page, with a small table of contents auto-generated that points to the headings on that page.

One Limitation

There’s a small technical limitation with this template technique, though. The problem is that Mediawiki stuffs the template into the main content area dynamically at run-time (you can’t manually call the template wherever you want it to appear, I don’t think).

As a result, if the page title spans two lines, it pushes the beginning of the content down a bit and subsequently also pushes down the location of the inserted template. Even with absolute positioning, because the template appears inside the main content area, which is styled with a relative position, the position of the template will always adjust if the parent div box adjusts.

A Workaround

Fortunately, there’s a workaround for this. By adding a statement to the localsettings.php file, $wgAllowDisplayTitle = true, you can then change the page title to a custom display. You just add {{DISPLAYTITLE:custom title}} to the page and change custom title to your shorter title. It’s a small hack, but not too cumbersome.

And why might you have long titles, you ask? Because with wikis, you often have a lot of content from different projects on one wiki site, so you need to call out the application as a prefix in the title, such as “Swordfish Application: Finding Environments for Exchanges.” If you left off the “Swordfish Application” part, your topic wouldn’t appear as accurately in the search results. Hence the long titles.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

An Electricity Fast

First, a brief bit of news. All the lights in my house are off because Jane wants to do an electricity fast. It’s a Thoreauvian experiment to see what you gain when you give something up. For the past couple of days I’ve been moving about with a candle, or staring at a computer screen in total darkness. I can’t cut off all electricity because that would be a little too extreme — food in the refrigerator would go bad, my side job with WordPress consulting would tank, my blog would slow to a halt. We made agreements about certain allowances. But by merely turning off the lights, it’s amazing how this puts you into a rhythm (or would if I were to turn the computer off).

Time to Take the HAT Off

Back to the topic at hand. In my last post, as I diligently looked into SEO and the importance of help’s visibility in Google, I found that help authoring tools have poor SEO. This is partly due to frames, partly due to the fact that few users will link to help content, and also because HAT code isn’t architected in an optimal way for the web.

If we plan to keep step with the web, we have to use a web platform. As a general trend, I think help authoring tools are going to fade because (a) they do a terrible job at SEO, (b) help authoring tools are poor at collaborative authoring, (c) help authoring tools fail at social media and interactivity, (d) help authoring tools don’t leverage the plugins and extensions of web platforms such as WordPress, Drupal, and Mediawiki, and (e) help authoring tools are expensive compared to web tools.

Additionally, the importance of single sourcing the long print manual is becoming less of a demand (have you handed someone a 100+page manual lately that someone accepted with eagerness? ) I predict that in several years time, we’ll see a major shift towards web-based tools in tech comm, especially wikis.

As a final nail in the coffin, check out this video on social media. It argues that social media presents the biggest shift since the Industrial Revolution.

After watching this video, it seems unlikely that the traditional HAT will be the default tool for software user instruction in a few years.

On to Wikis

Until now, I’ve explored ways to organize content with the assumption that we’re using a help authoring tool. Now I would like to shift to the same discussion but with a web-based platform in mind: the wiki.

Wikis pose serious challenges when it comes to content organization, because all you have are essentially links. In describing different information architecture patterns, Donna Spencer calls wikis a flat model. With wikis, you often don’t have a table of contents feature to organize your topics. You have a page that links to another page that links to another page ad nauseum.

Which Wiki?

Given that there are more than 100 different wiki platforms, it will be difficult to generalize about wikis, because surely some wiki out there (for example, Confluence) probably has a fine TOC feature that collapses and expands. Other wikis may not have flat structures (for example, SharePoint’s wiki system, which provides you with metadata and views). But I will take as my example the quintessential wiki plaform: Mediawiki. (Wikipedia uses Mediawiki as its wiki engine, in case you didn’t know.)

A Maze of Chaos

A few years ago, at a Doc Train West conference, I interviewed someone who asked to remain anonymous. It’s the only anonymous podcast interview I ever conducted (out of about 130 podcasts). The next day, the person asked me to not publish it. Why? The conference had a lot of sessions about wikis. The interviewee explained that at her work, they had created a wiki. It started out okay, but it soon degenerated into a maze of chaos. It had become an embarrassment, an impossible black hole of content. She was cautioning against wikis.

Part of the problem with organizing content on wikis is lack of control. As soon as wikis become a collaborative effort, with multiple authors, the organization becomes much more challenging and is likely to suffer from inconsistency and chaos. I don’t know if this is inherent in collaborative authoring projects, or if it’s inherent in the wiki architecture, but eventually wikis become so disorganized that search becomes the only method of navigation.

Case in point, check out the WordPress Codex. If you have a body of information this size, there’s no clear way to organize it. You end up with links that you can kind of group together, into Getting Started, Design and Layout, Advanced Topics. But then you also have general groupings under vague topics like Working with WordPress and About WordPress. There’s no clear path through the content.

Wiki Categories

One way to organize wiki content on Mediawiki is through categories. Many people reading Mediawiki wikis don’t realize this, but each page is usually tagged with a category. For example, the Wikipedia page on Technical Communication is labeled with the category Technical communication (scroll to the bottom to see it).

The category label appears at the bottom

Categories on Mediawiki work just like categories on WordPress, except that the method for adding them is less intuitive. Somewhere on the page, you just add the text [[Category:Technical Communication]]. This creates a category link that will pull together all other Wikipedia pages tagged with this same category, as shown in the image below:

All topics in the Technical communication category on Wikipedia

This method of content organization isn’t bad, except that the category link is buried in the page’s footer and is practically invisible. Some Mediawiki skins display the category link more prominently.

Still the Same Challenges

Despite this system of categories, you still run into the same issues of content organization. If you click the Discussion tab for this Technical communication category page, you see the following exchange between users:

Does Category:Specification languages really belong in this category?—iFaqeer (Talk to me!) 04:25, Nov 30, 2004 (UTC)

I’m not totally sure. I’m still trying to get my head around how this category system is supposed to work. I think there’s definitely some connection between technical communication and spec languages (like UML) but I don’t know whether it belongs as a subcategory. It certainly looks strange to be all by itself. If you’d like to remove it, I wouldn’t object. –LeeHunter 23:06, 30 Nov 2004 (UTC)

I don’t think it needs to be a subcategory. Perhaps it belongs as a link from an article discussing how some technical writers deal with them in their day to day jobs. Maybe as part of the main Technical communication article??–GeoffPurchase 04:33, 2004 Dec 1 (UTC). The contents of Specification language don’t quite co-relate with the contents of that category. Does it? I mean, do they? The category seems to list what I would call “mark-up languages” while the definition is for a kind of programming language (which might be a superset of what is in the category). If I am right, the latter is definitely TC-related; the former is only marginally so.

I am not very well-informed on either of the two areas my confusion spans, so I would like someone else to chime in. And the reason I keep posting this here is that it’s kinda lonely at Category talk:Specification languages.—iFaqeer (Talk to me!) 05:12, Dec 1, 2004 (UTC)

Does specification language fit into the Technical communication category? Maybe. I’m not even sure what a specification language is. Strangely, when I looked at this more closely, specification language didn’t make it into the Technical Communication category. But Specification did.

Categories and Subcategories

The fun doesn’t stop here. Each category can also have subcategories. Or looking at it from another perpsective, each category can also be grouped under a parent category. When you’re looking at a category, such as the Technical Communication category, scroll to the bottom to see which parent category it belongs to. You’ll see that Technical Communication is categorized under Written Communication | Communication | Technology. Technical Communication is a subcategory for these categories.

Larger categories that Technical communication is grouped under

If you click these parent categories, you’ll see that they’re also grouped into higher-level parent categories, namely, Human skills | Information systems | Language. Human Skills is a subcategory of Skills | Humans | Human behavior. Humans is a subcategory under Anthropology and Hominina. Hominina is a subcategory of Apes. Apes is a subcategory under Primates. Primates under Mammals. Mammals under Vertebrates | Tetrapods | Synapsids.

Vertegrates is a subcategory under Chordates. Chordates is a subcategory under Animals | Phyla. Animals is a subcategory of Life | Natural Sciences. Life is a subcategory of Nature | Phenomena | Fundamental | Main topic classifications. Nature is a subcategory of Main topic classifications | Fundamental. Fundamental is a subcategory of Articles, and then it goes to Content > Parent Categories > Categories > and Contents.

The exact taxonomy depends on how you climb up the topics. Like a pedigree chart of ancestors, you can take multiple paths. But here’s the general layout of categories and subcategories. I bolded the path I took to climb up to the highest level of categorization:

Contents
Categories
Parent Categories
Content
Articles
Main topic classifications | Fundamental
Nature | Phenomena | Fundamental | Main topic classifications
Life | Natural sciences
Animals | Biology
Eukaryotes | Zoology
Animals | Phyla
Chordates
Vertebrates | Tetrapods | Synapsids
Mammals
Primates
Apes
Anthropology | Hominina
Skills | Humans | Human behavior
Human skills | Information systems | Language
Writing / Communication
Written communication / Communication / Technology
Technical Communication

I don’t know about you, but I feel a special pride in the way this plays out, and how in just a few levels, you move from Technical Communication to Chordates. Maybe this is why the Category label appears at the bottom of the article and search appears at the top.

At the Highest Level, Categories Fail

It’s especially interesting to look at categories at the highest level: Contents.

One of the highest levels of categorization on Wikipedia

At this level, content is grouped into such general categories that it’s almost useless — categories by status, by topic, by function, by association, by type. If you were starting out here, would you ever drill down into Technical communication? It would take a miracle. But at the lower, more specific level, the category model does seem useful.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

This podcast on Trends in Technical Communication is a recording of a presentation I gave at the Missouri State University Workshop for Teachers of Technical Writing on April 22, 2010. Although trends in technical communication could cover a variety of topics, I chose to focus on four trends: hybrid roles, social media, collaborative authoring, and multimedia. Here’s the description of my presentation:

In a sea of ever-changing technologies, tools, and methods for documentation, technical writers often find themselves gasping for air trying to keep up. At the lead of the current trends, the following topics continue to gain traction: multimedia, such as screencasts and other video content; wikis, as well as other collaborative authoring tools and methods; hybrid roles, especially with usability, quality assurance, and audiovisual tasks; and finally the messy, fragmented content of social media, which stands in sharp contrast to structured authoring.

Blog Sponsors

• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree