Is Collaborative Authoring Over-Hyped?
If there's one business buzzword that you hear all over the place, "collaboration" must rank in the top 10. When it comes to technical writing, if we open our arms to collaboration, giving a warm embrace to "collaborative authoring" is only one more little step. It feels so tolerant and embracing to be collaborative. It fits in with Web 2.0 and the trend toward interactivity. In reality, collaborative authoring is little more than a euphemism for the idea that "anyone can write."
Last week I had a pivotal conversation with my colleagues about the topic of collaborative authoring. I was trying to remember what initially pointed me in the direction of wikis (the consummate collaborative authoring platform) in the first place. About three years ago, I was working on a project when another department asked for the source files, essentially cutting me out of the authoring process because InDesign offered no way to collaborate. I wrote a post titled The Case of the Stolen Documentation telling this story.
Each of my colleagues shared their own experiences with customers desiring editorial control over the documentation. (By "customers" I'm referring to business departments that sponsor IT projects, not end-users.) One customer group went so far as to buy their own copy of Flare to maintain and update the help. It was a nice idea, but the results were less than impressive (not because of Flare, but because the customer group using it didn't include professional writers).
Another customer leveraged a small army of subject matter experts (SMEs) to help write content, but the results were often unusable. They produced a lot of poorly written text that, in the end, turned out not to be that helpful for people learning the software.
Another colleague crowdsourced the documentation among a group of volunteers (at my recommendation), but the management overhead nearly paralleled the saved writing time.
For my experience, I noted that customers often make a big deal about having everyone on their team be able to update the content, but then no one makes any updates at all, beyond a few words here and there. Most people want the possibility of control without any of the responsibility to do the work.
All of us agreed, somewhat reluctantly, that none of us has had much success with collaborative authoring.
If we were collaborating with professional writers, I'm sure the results would be different. But most of the time, the collaborators were customers who wanted to own and maintain the content. Shared control of content sounds like a good plan in theory until the reality sets in: customers don't maintain the content much at all, the edits they make are sloppy and unorganized, the product's quality takes a turn for the worse.
Many other professionals in an IT organization never encounter this request for collaboration. When a designer creates an illustration, does the customer ask for the source files so the customer can make needed updates? Does the customer ask developers for the source code so the customer can make needed updates? Does the customer ask the application systems engineer for the password to the server so that the customer can optimize it if need be?
No, but somehow writing is different, because didn't you know, anyone can write? Yes, just give the customer the control he or she wants. Don't be such a writing snob. Let's all work on this together.

Under the allure of collaborative authoring, we bend over backwards facilitating the sharing of content through wikis and other collaborative solutions, only to realize time and again that good writing skills are a rare possession.
Yes, even though most people feel they can write well, and therefore ask for shared ownership of content, their writing skills don't often lead to creating good help documentation. Writing is a spectrum skill, so at the lowest level, yes, just about anyone can write a sentence or two, as with email and Twitter. My five-year-old can write her name, in fact. But as soon as you climb up the scale of difficulty, writing requires more and more advanced skills, to the point that writing quality content that solves customer pain points in relevant, easy-to-understand ways is a result only professional writers can achieve.
For more on the topic of "anyone can write" (or writing as a commodity) see my previous post, What Does It Mean to Know How to Write, and also Mark Baker's philosophical reflections, It's Time for a New Doctrine of Technical Communications and Scott Abel and Jack Molisani's Tech Comm 2.0: Reinventing Our Relevance in the 2000s.
Let's return to the question: What's the answer to the customer who asserts that he or she wants to own and maintain the content once we draft it? Do we deliver it up in a format he or she can update, like Microsoft Word? Do we get the customers licenses to help authoring tool clients that allow them to edit in the browser (such as with Author-it Live), or on their own machine? Do we resort to wikis and other online solutions that allow our customers to log in and change/update/revamp/ruin the content? (See my essay My Journey to and From Wikis for my experience following that route.)
Although all of us admitted that our efforts toward collaborative authoring weren't that successful, we also confessed that nearly every customer wanted to own the content -- the source files -- once we completed our work so they could update the content. What do you do with these requests? Can you really say no to the customer? Can you decline the project sponsor?
My colleague noted that if we insist on owning the content, we have to own it throughout the lifecycle of the content, which means ensuring we stay updated about each and every update as long as the product is alive. If we host the content on our server, we should regularly review the content against updates to the applications and make sure we're keeping the content up to date -- long after our involvement with the project has ended.
And if we own the content, why not keep our content in whatever format we prefer (DITA or Flare or some fancy custom XML schema we've developed) and deliver a non-editable help output, such as a webhelp or PDF. If people want updates, let them send us a request or log a bug in JIRA.
Is that too harsh? Perhaps. But I've been playing the collaborative authoring role long enough to grow tired of it.
I'm curious to hear how you have handled requests for shared ownership of content, or how you approach collaborative authoring with non-writers. Surely for those teams writing in DITA, using Flare, Robohelp, or other HATs, collaborative authoring isn't something that anyone can just jump in and do, as with a wiki. For those using wikis, are the edits from customers frequent and regular, or are they sporadic and poor?
About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
Hey I am so happy I found your weblog, I really found you by error, while
I was browsing on Askjeeve for something else, Anyways I am here now and would just like to say thank you
for a fantastic post and a all round entertaining blog (I also love
the theme/design), I don't have time to go through it all at the minute but I have saved it and also added in your RSS feeds, so when I have time I will be back to read much more, Please do keep up the superb work.
Quality posts is the secret to be a focus for the people
to pay a quick visit the website, that's what this website is providing.
Definitely believe that which you said. Your favorite reason
appeared to be on the internet the simplest thing to be aware of.
I say to you, I definitely get irked while people consider worries that they plainly don't know about. You managed to hit the nail upon the top as well as defined out the whole thing without having side effect , people could take a signal. Will likely be back to get more. Thanks
Tom, I like your take on identifying the need for collaborative authoring before saying YES to it.
It is true that many businesses (client itself, or project teams) are keen to plan documentation based on collaborative authoring; however, where many falter is to do required cost-benefit analysis of this approach.
- The expected participants consider it (or are made to take it as) merely writing, and which is not true.
- Knowledge of a HAT alone (how to import HTML/CSS, update TOC, and generate the primary layout) doesn’t make collaborative authoring a success.
- They don’t spend enough time to realise that if measurable benefits of CA is A and the cost of foreseen issues (costs, training, review cycles and so on) is B, what is the ratio of A/B (or B/A).
I recall that a Melbourne based business approached me few years back for their documentation requirements. The client had licensed RoboHELP and wanted all project files WebHelp not because it was of course his property, but because he wanted to update it later, self. The client (the project team, the dev team of the client himself) tried to update a few pages and the result was a poor updated document. The style guide was ignored (or abused?) and the images used as screenshots were named as image1.gif, image2.gif, image3.gif, and so on. It took me weeks to correct everything to set the document in right order. The result was that he had to shell out 80% more that what he had originally allocated for that documentation task.
PS: I also recall that many years back, the water supply pipe in my courtyard was broken and I called up a plumber. As he was fixing it, I watched very carefully how he assembled the T, elbow, and the solution, got that properly aligned and fixed it. It seemed so easy to eyes and as he was about to repeat the process for another broken joint, I murmured this is not something too difficult that you are doing and you asks for INR 300 for this small task? He looked at me and replied I am a qualified engineer, and I have fixed 300 pipes in last 4 years. Try doing it and I will pay you double of what you would have paid me. And I was quiet :)
I will say that CA is highly over-hyped. Many business are jumping into it, just to be part of the crowd, and nothing else.
Vinish, thanks for sharing your experiences with collaborative authoring. What you say is really interesting. The plumber story is funny as well -- those copper pipes are trickier than one assumes, I believe.
I was talking to a SME the other day to ask how the Flare experiment went (he's the one I wrote about here, who bought Flare to own the doc that the tech writer produced). The SME emphasized that he only wanted to make small updates here and there and not bother the technical writer (or go through the hassle) to make the updates. I can see that and agree. If that's the case, he might just edit the HTML files of the generated output. It sounds somewhat easy, but as you relate with the Robohelp experience, it's quite easy to muck up the files.
Thanks again for commenting.
That's interesting. The internal "customers" for the company I do most of my contract tech writing for are not native English speakers. They do not want source files to update docs, or to take over ownership of docs that come from Tech Pubs. It sounds like your work environment is very different.
I think when you are looking at parallel situations you could take more of a big picture view about source files. For instance, in addition to contract tech writing, I'm an author. When I need art, I hire an illustrator and I do need the source files. Sometimes I go in and make small changes to the art, or lift a portion of an illustration for use elsewhere. It's expensive and more time consuming to contact an illustrator for that sort of change. Also, having the source files for the illustrations gives me more formatting options for books that are printed. It’s good to have those vector graphics, even if the publisher wants TIFF format.
If you move outside of IT and look at developer groups, when it comes to ODMs, yes the customer (the company that will sell the end product to the customer) does want the source code in some cases. That would be specified in the contract. And of course there are open source applications where people do access the source code. The difference is that people are more likely to realize they don’t know how to work with source code, than to realize that they aren’t especially good at writing.
I like reading your blog. : )
Betsy, thanks for adding your comment here. I especially like what you say here: "The difference is that people are more likely to realize they don’t know how to work with source code, than to realize that they aren’t especially good at writing." I completely agree.
I think you're right about being willing to hand over the source files. Although few designers I work with are willing to give their source files, if it were a third-party contractor, of course I would expect to receive the source files.
But in giving the source files, I think we shouldn't have to convert them to a format that others can more easily work with. I suppose I could generate an MS Word output, but I'd rather just hand over the Flare files happily, and see what they try to do with them. I'm guessing their reaction would be similar to what you describe above.
Tom,
I wrote a blog post back in January titled How Content Producers Get Collaboration Wrong (http://everypageispageone.c...). The essence of my argument was that good collaboration segments a problem so that
a) each person focuses on the part of the task they are good at
b) the need for people working on different parts of the project to communicate with each other is minimized
I'm an occasional collaborator in the international banking system. Last April I used an ATM in San Diego airport to get some US cash, with the funds being withdrawn from my Canadian bank account. Behind the scenes this involves some complex international data exchanges, and yet I was allowed to complete the entire transaction myself, without supervision.
I could do this because the international banking system is well segmented. My part of the transaction was conducted using only terms and concepts I was familiar with, it asked me only for information I knew, and made it impossible for me to interfere with data belonging to anyone else.
A wiki, of course, is the very opposite of a well segmented system. Even with a permission system and templates in place, a wiki presents essentially a blank page. It expects each collaborator to do the whole authoring task.
All of our tools are this way. Desktop publishing tools are designed specifically to put the entire authoring and publishing process in the hands of a single author. And even when we move to structured authoring, we generally demand tools that look and work as much like desktop publishing as possible.
We work in an individual craftsman fashion, and when we invite collaborators, we ask them to work as individual craftsmen as well. And, as you point out, most of them are not well qualified to do so, let alone interested in doing so.
I have had great success getting developers to collaborate on information development by segmenting the task. Essentially, I give them a form to fill in, capture the form data as XML, and then merge the data with authored or boilerplate content.
But this kind of approach means that writers too have to be working in a segmented system. They have to give up the individual craftsman model and work in a new way.
This is another aspect of something I wrote about last month (http://everypageispageone.c...). We want to do all sorts of new things, like collaboration, reuse, online delivery, ebooks, etc., yet we don't want to change our tools, or processes, or our designs to accommodate these new things. We just make longer and longer shopping lists, and complain when vendors don't deliver. (For example, see Sharon Burton's version of the shopping list: http://www.sharonburton.com...).
We can't expect to collaborate successfully if we ask our collaborators to do all of the job for part of the content. To be successful we need to segment the task so that our collaborators do only that part of the job they are qualified and motivated to do. To do that we need to make fundamental changes in our processes, our designs, and our tools.
Hi Tom,
I'm sure everyone who has tried to wrangle non-professional writers as a resource to a limited docs team has felt some of the pain you succinctly sum up as "the idea that 'anyone can write.'"
At at a previous company (back in 2005), we faced this challenge along with a mandate that we use a wiki as our authoring/delivery platform. We chose MediaWiki as a low cost solution and then adapted it extensively. I had hired a WriterProgrammer to help document the many APIs that lacked documetation, and her programming cabiliities proved crucial in our ability to achieve the following with the wiki (the list is not exhaustive):
•Compelling an author to choose from a list of structured document templates (complete with brief instructions) when creating a new page
•Setting of document completion state on each page with an accompanying highly visible icon, i.e. First Draft, Second draft, Technically Reviewed, Final , etc. (the exact state names escape me now), with the default behavior being that as soon as anyone edited the page, the state for that page automatically reset to First Draft. It took an authorized wiki admin (one of our professional writers) to reset the state to a higher level. Given that we were also alerted (through MediaWiki’s built in RSS feeder) to all edits, this feature enabled us both to maintain ultimate control of the content and alert our end-users in an automated/semi-automated way to the state of each individual document. The benefit was that we could be extremely agile and make all our end-user docs (no matter their state) always available without worrying that our end-users would find the quality of our docs poor. Our customers appreciated very much having access to documents that were incomplete, and using the feature in the bullet below, could alert us to a need for attention on a particular topic.
•A rating button with accompanying feedback form on every page
•Use of TinyMCE and FCK Editor HTML editor plugins (at the time, they both required some programming expertise to add to MediWiki)—this feature reduced the need for knowing wiki syntax to knowing how to create links to other pages
•We also overcame the flat file drawbacks of wikis by adopting a page naming convention that included the document type, for example: Task : Adding a Page to this Wiki), we also made landing pages with links to each of documentation areas (this was rather manual and laborious—wiki’s aren't good at everything, but what HAT is?)
Using this approach, we were able to teach non-professional writers to produce fairly high quality content (especially over time as each page matured). Our non-professional writers included our WriterProgrammer (at first), an intern originally brought on to help with programming, some 15 engineers, and a few faithful members of our small external community. Using structured document templates also improved the speed and quality with which our professional writers created content. How scalable such an approach would be in a very large community would have to be seen, but this solution worked for us.
You've touched on a universal issue whenever people are provided tools--we all think we know how to use a hammer, but only the skilled user of that tool can pound in a 16-penny nail in 3 whacks without denting the wood. Ironically, the rest of us may feel just as confident, even though we only know enough about the domain to be dangerous! That tilted perception has a name: the Dunning-Kruger effect (http://en.wikipedia.org/wik...).
To help contributors be more effective despite their own perceptions about their ability, you really have to work with a palette of approaches. In general, a wiki is merely another hammer--we all think we know how to use it, but the wise foreman will assign the junior worker to nail the studs or other hidden work, and will leave the drywall and trim work to the more experienced worker. In effect, you must curate your contributor base just as you need to curate their work. If anything, that's what American Idol does: the audition shows get early value out of the ones who are so bad they can't recognize it, but the process is ultimately aimed at selecting the pool of performers who will be in the summer tour--the team that produces the longer term revenue windfall.
The right tool for the user is important as well. I can't get over thinking how much Auto-Tune would help even the worst auditioners, and that is exactly what some of suggestions above are about: helping contributors get the words in the right key, as it were. Permissions and roles are other components of prudent collaboration management--these are how you keep bulls out of the china shop, to change the metaphor a little.
So if the goal of our craft is to get the right information to the right user at the right time in the right format (yahdah), then from the outside looking in, the goal of effective contribution is providing the right tool to the right user in the right context so that they can contribute the right information in the right structure. Or some variation on that pattern...
I've been hesitant to post now that you've turned on wikis, but I thought I'd share my experience with collaborative authoring.
Late last year, we identified 200 "must have" topics. Since I was busy writing product documentation, there was no way that I, the lone tech writer, would be able to write 200 additional topics in any reasonable time. So we allowed people across the company to choose topics (and set up an award system for writing topics), and created a review team of six experts. I quickly put together some style guidelines and created a template for people to use (which included some tips and suggestions).
We use a wiki-based system (MindTouch), and it includes permission controls. I gave all of the internal authors an account and Author privileges, and when someone created a page, I changed the permissions on the page so that it could be viewed only by internal users. Once the reviewers approved it, I would do a final, very quick pass to fix any structural issues (adding headings, typically) or formatting problems, and then I would publish it by changing the page permission to Public.
We had 200 topics written by January (just maybe fueled by desire to win an iPad). Although that project is complete, we do get people asking to write articles (rarely, but it happens), and we have two ongoing documentation projects that are written by SMEs, where I act as a consultant (some editing, but mostly answering questions about using MindTouch and providing suggestions about structure). Very few users are comfortable editing the documentation, but I will get 1-2 updates a week from SMEs inside the company (usually corrections to API reference docs), and a few comments a month from customers.
Sounds like a great outcome to a pressing problem. I'd love to be in your shoes. As a lone writer, I get hardly any feedback from within or without the organization as it is except for people to ask where some (unwritten yet) content is. I just came across the concept of a doc sprint that sounds a lot like your 200 topic "sprint" - I think I may have to try something like that to get more coverage in my content.
Nice to hear a Wiki-publishing success story, Neil!.
A reasonable scheme of curation, permissions, and a controlled path to publishing such as yours proves it can be successful.
I'm guessing, but 200 topics seems considerably more manageable than the quantity Tom appears to be dealing with. If I'm right, that doesn't hurt, either!
Thanks, Frank. To be clear, these were 200 topics that we needed in addition to all of the user docs that I was already writing. Because we wanted those topics ready in 2-3 months, there just wasn't any other way to get that information written and published.
But you're right, and this wasn't a case where we opened the documentation to the entire world. We'd like to try that, though, similar to how Autodesk does it (http://wikihelp.autodesk.co...), where user-created doc is reviewed and approved, and includes not just "how to use this product" but "here's a neat way that I use the product." But Autodesk has more than one writer, so it's not the same degree of limited editorial resources that Tom was facing.
I'm wary of drawing conclusions, but it takes a lot of work for one writer to maintain an open wiki system, and it's probably just easier for a single writer to use closed documentation system and funnel input through a ticketing system (to track doc bugs and enhancement requests).
Great discussion here! You've obviously touched a nerve, Tom...
I was confused by the level of chaos you described in the intitial post, until I saw in one of your responses today, "our platform was a wiki."
In any collaboration effort, there must be rules and structure, and wikis are biased toward all-out contribution, and little control over display. Managing what your customer sees as 'company instruction' is all-important, and requires a lot of attention--in any tool, but if the wiki is actually the publishing vehicle, I can only imagine that a great deal of caution must be used in creating a process that enables the just-right amount of control.
Alan put it well: There is no one-size-fits-all solution for collaborative authoring (or anything else in tech comm).
In some cases the business case is more on the "right-enough is good enough," and in others, poor instructions can have huge costs to the business. Every one of us has to stand up for making these choices in the best interest of the business. Sometimes that may not be in the best interest of clear writing, but it will still enable us to produce the best content possible to support the business. And we'll continue to learn about the need for good analysis in devising the publishing rules that support the business need.
The core message of your post seemed to be anti-collaboration, but that's not realistic. Managing how that collaboration takes place, and how the fruits of collaboration reach the audience, is hard work. And it's not writing, but it sure impacts what the published word says.
Thanks for the honest and insightful post, Tom. As I read it and the comments, I wavered between laughing and crying (you know it's the same release... but I digress.)
We have 'real' documentation, created by professional writers, pages on a wiki, created by anyone, and information tucked away in emails, jira tickets, and who knows where else.
At the moment, I'm trying to 'tame' our wiki. It's a daunting task. There's some frustrating duplication of content. For example, there are no fewer than 10 pages, each describing a different way to set up a particular machine. And all 10 are incorrect!
So I'm attempting to impose a structure through the use of templates for navigation. At the moment, I'm letting the content dictate the structure. As I'm only 1/4 of the way through the corner of the wiki I'm taking responsibility for, I'm not sure how it's going to turn out.
Thank you for the wonderful and thoughtful post Tom. I've collaborated with other writers in multiple companies on multiple projects. Not always the same authoring tool. Typically, a successful experience. I think it has to do with having the same standards and understanding of the goal of writing.
However, if I collaborate with non-writers on technical documentation, the experience is always difficult. "It should be shorter" or "we need a higher rank on SEO" I hear a lot. Since my primary standard is write enough content to make the user successful with the product -- well, it is hard to agree on what to write.
Deep learning has been much better suited to being delivered on paper. There's no screen flicker, it's more portable, there's less eye strain etc. With passive electronic ink devices (e.g. Kindle) and retina screen tablets (e.g. the iPad 3), it's now possible to present long and deep content in an electronic format.
By the way, as a side note, it's interesting that this post of 1,200 words was much more read than my other post on my journey to and from wikis, where I really shared a lot more of my disillusionment with having non-professional writers create content (both blog articles and help content). That other post was 10 times as long. I guess the length of the web maxes out at about 2,000 words. After that, people just don't want to read something longer. This amazes me because books are still popular, esp. ebooks. I think I needed to put that other post into an EPUB format. I did create it as a PDF, though. And I created about a dozen illustrations.
I actually downloaded the PDF so that I could read it off-line. I thought it was a great story of your progress through the world of wikis ;>)
Thanks for sharing your process, John. We use SharePoint too. I'm curious to know whether you use Word 2010's synchronization feature that allows one to simply update Word docs locally and have them sync to the Sharepoint server.
It's great to hear all of these different processes.
My group's SMEs have opted to post MS Word docs (since they cannot / do not wish to learn FrameMaker) to SharePoint with write permissions allowing everyone to update docs as they please.
While at first this may sound like a tech writer's nightmare, fortunately we are still small enough to where this works out somewhat OK. As soon as an SME posts a document to the site, my subscription to the site notifies me of the change, whereafter I immediately check out and edit the doc according to the group's style guide, and check it back in - ready for public consumption.
While this process is not perfect, it works for our smaller group of writers and engineers. As the group grows, update activities will eventually become so voluminous, that it will be difficult to keep up. We will have to incorporate a more formalized editing and publication process.
Edits from engineers are frequent, and their quality ranges from poor to very good.
To Craig, while I agree on drawings and illustrations, a night at karaoke usually convinces me that most people (including me) think they sing better than they do:-).
To Tom, two thoughts:
-
A lot of us have had internal customers who wouldn't want to own content if you held a gun to their heads, so in one way it's nice that they're interested:-).
-
It seems as though you are in a situation where you're negotiating independently with each customer group, and coming up with a different process, and maybe even different tools, for each interaction. I think those negotiations need to include a discussion of ownership up front, so you know in advance who will own the completed work and who will be responsible for updates and maintenance. You should never be surprised by a request for source; that should be worked out in advance.
I would also consider being a bit less flexible in changing tools, and a bit more flexible in giving away ownership. That is, rather than try to fit into every process and toolset imaginable, it might be better to focus on a limited set of tools that you work with well, then operate in two modes. In one mode, you own and maintain the content using your tools and processes (even if others contribute in controlled ways), and in the other, you develop content however they want it, but then give it away and transfer full responsibility for future maintenance. The one thing you don't want to do is hand over source to another team, then find yourself still maintaining it.
Thanks Richard. I always appreciate your perspective and like your take on the situation. You're right that establishing ownership up front is key. That should certainly be outlined in the project plan.
Re the two models, I like that as well. If we author in Flare, we could promise to deliver a Word document that has all the information in a way they could edit. Or I guess they could edit the html files from a webhelp file. Most people tend to neglect it, though.
or use MadCap Contributor
We have found that wikis work well for our technical content that is written by developers on the wiki and then made available for services installers to use at customer facilities(we have a very complex system). We have a full-time writer that cleans up and "manages" the content--ensure it's tagged and cross-referenced appropriately, etc. We then publish the wiki content to a read-only wiki where installers can add comments to alert the writer about errors or missing content.
I would very much hesitate, however, to use such a system for product users that require help files. All the drawbacks that Tom mentioned are in full play in those circumstances. The writing team maintains ownership of help documentation.
Pam, thanks for your comment. What you say sounds like it matches my experience. The developers writing for developers model seems to work, but not SMEs writing for end-users. I like your transfer of content from a writable wiki to a non-writable wiki. Thanks for sharing.
I find it fascinating how most people believe they write well, but they don't have similar illusions about their ability to sing or to produce drawings or illustrations.
I just have to say (rather tongue in cheek) to Craig - "Have you never seen Americal Idol? Not only are there plenty of people who think they can sing (and can't), but they're more than willing to do so on national television.
As a singer and a writer (I let others judge my professionalism - so far so good on both counts), I never cease to be amazed at the absolute bravado with which many somewhat delusional people eagerly share their very meager "talent."
Never been to a modern art exhibit? The person standing in front of a Clyfford Stills or Jackson Pollock work saying --- I could do that. Or how about photography -- Instagram does not a photographer make --- or so say all the professional photographers who sound like writers saying "everyone thinks they can write."
Excellent observation, Craig. I think that says quite a bit.
As I read through this article, Tom, and then through the comments, the word ownership kept coming to mind. Collaboration is quite different from simply handing over the files to whoever asks for them. With true collaboration, customers (other groups in the organization and literal customers) can contribute content -- but the content and the process are always owned by the professional writers. If you do it that way, you'll have a few more success stories to share the next time you're chatting with your colleagues.
Larry, thanks for sharing your insight. I like the distinction you make between ownership and collaboration. That's an important element to consider.
Can you see my comment to Alan above? I know you use DITA as well, so I'm curious to know how you pull structured content out of SMEs.
I've got a question, Tom. When you threw open your sources to SMEs, what processes did you implement for ensuring accountability and readability?
It's one thing for SMEs to ask for access to the sources--after all, they are the ones who know the subject. But along with that access should come a process for ensuring that they update the content they're responsible for.
Your SMEs probably have a wide range of writing ability. At some point there should be a process for ensuring that the writing is clear and consistent. Yes, it means that you'll be doing some editing, but you would anyway if you took raw content from the SMEs and re-wrote it in your authoring system.
We could probably do a much better job at defining a specific authoring process, but because our platform was a wiki, anyone could create a page on a whim. I tried to monitor Recent Changes, but in a large organization, I didn't have the bandwidth to be a dedicated content manager of 20+ products.
I tried to ensure some quality, but usually what happened was someone would create a page that was a working draft. The draft would more or less stay a draft. Then someone else would create a similar one, without realizing another page already existed. The two wouldn't be linked or referenced at all. Then many SMEs abandoned the content when they no longer needed it, so it was out of date.
Perhaps the problem was that anyone could create content, no one owned it, and no one exercised strict control over the wiki. When I arrived on the scene, it was already a giant mess. I could have spent weeks just verifying whether certain pages were still needed or up to date.
I should have been ruthlessly deleting poor pages, perhaps. But there was no budget to hold each person's hand as they wrote content on so many different projects and topics.
Did end-users care? Yes, they complained they couldn't find anything, were often confused by the mixing of product with project pages, and felt a lot of content was outdated, not to mention non-authoritative.
For me, the bottom line is whether collaboration benefits the company as the whole.
Sure, writing skills may not be as strong in some departments. But if "good enough" collaborative content saves the company money in the long run and satisfies customer needs, I think you'll be hard-pressed to justify a "deliver a non-editable help output, such as a webhelp or PDF" approach that encourages information silos.
I agree with Ellis's comment about getting input from SMEs. More and more of our clients are asking for content processes that support reviewing and part-time authoring by SMEs.
Alan, thanks for your comment and perspective. Also, thanks for your response blog post: Let Go of Your Silo. You bring up a good point -- walling off contributors may contribute to a silo of writing. Here is where I'm curious to learn about how Scriptorium handles this.
As I understand it, Scriptorium often helps companies implement structured writing solutions, such as DITA. Surely you don't get SMEs to write in DITA, so how do you pull structured writing out of SMEs?
I've written previously about the collision between social media and structured authoring. On the one hand, social media, for example, what you see in wikis, forums, blogs, and Twitter-like sites, produce largely unstructured content, which is hard to work with. You would have to transform structured content into some schema to transform it, right?
On the other hand, structured content allows you many more publishing and transformation possibilities. If you could comment on how you pull structured content from SMEs, I would like to better understand how you do this.
Also, I think our writing scenarios differ. If you're a consultant working with companies, you help those companies implement authoring solutions regardless of the quality of their writers. I'm a tech writer inside a company, and I grow tired of mediocre writing (if done at all) when I know a dedicated technical writer could do a much better job. Many times it's not a matter of budget but rather an assumption that all writing is poor so by default anyone can write.
Tom,
You hit on something important, Tom: not every company's situation is the same. There is no one-size-fits-all solution for collaborative authoring (or anything else in tech comm).
While not all of our clients are in structure or DITA, many are. There are tools and technologies that enable SMEs and other part-time contributors to write structured content--without them even knowing it! For example, you could create web forms that offer guided authoring; under the covers, elements are applied to the content strings.
And this is where structured wiki content is quite valuable. This helps to "force" other contributors/collaborators to adhere to some standards. Additionally, I've found that instead of giving a full wiki page for collaborators to contribute, try using a simple form front-end for data entry -- it allows contributors to add the "meat" -- that updates a "templated" wiki page.
A template is useful to suggest structure. It doesn't guarantee a good collaboration experience --- or a usable piece. I write on a Wiki for a large company. Our developers contribute code tutorials to our Wiki using a template. Time and time again I get feedback from these pages that steps are missing, confusing, or code is out of date.
I think we focus too much on whether this person or that person "can write." As Tom points out everyone can write to some extent. Many of our developers write well --- meaning no spelling errors, grammatically correct, and even sometimes engaging. None of that guarantees whether what they write is usable.
The standard should not be can you write but can most people most of the time use what you have written to accomplish a task unaided by a support call or an email to a forum. Only then can technical documentation be said to really provide a benefit to an company.
Rick, the templated wiki page would be ideal. I guess I'm not using the right wiki for that. Ideally you could create a template that would force all content into just the right structure, which you could then more easily transform and manipulate. What wiki offers this?
Confluence and Mindtouch have templates.
There can be good reasons for collaborative authoring.
Firstly, it can be a way of getting Subject Matter Experts to provide content. They are often more willing to dump information into a wiki, because it’s Web-based and therefore familiar to them. It can be easier to edit wiki content than edit a Word document (because wikis tend to separate content from "look and feel").
It can also make reviewing easier too. Not everyone knows how to use the review features in Word, but most people understand what the "add comment" button does on a Web page. Often reviewers print a document and scribble their comments all over it. If you can get them to comment online, then it's easier to take those comments and amendments and incorporate them into the document (less re-keying for you).
Regarding post project handover, if you're a 3rd party technical writing services company, it's inevitable you'll be handing over the source files. If the authoring environment is accessible via a Web browser, you have the opportunity to check they're not ruining the documentation by the amendments they make. You also have the opportunity to set up a post-project maintenance/editing arrangement for fixing any mistakes they make, and gain some post-project revenues. You can retain overall editorial control.
Ellis, thanks for the comment. Different scenarios will have different results, of course. We do have some devs who write documentation for the java stack, and your description matches their process. However, they seem to be unique in this writing, and who knows if it's any good (I don't know or use Java, so it's hard for me to evaluate). For other groups, they have a strong aversion to writing or editing anything, whether on a wiki, in a Word document, or on a scrap of notebook paper.