Accelerated Authoring™ @ Method M

Tech writing forums regularly get hit with questions in the vein of “Word has corrupted my styles”. And the answers that come in are useful for some cases. Such as:

• Always “paste unformatted”.
• Deselect the option to Automatically Update Document Styles.
• Deselect the option to Define Styles Based on Your Formatting.

However, what to do when my files already have helter skelter formatting? For this very need we have included “fix styles” in our Author Max toolkit. Details here.

Be a victim of Word’s automatic formatting “features” no longer. Equip yourself with Author Max and fight back.
Katriel

Four Flavor Falafel has opened here in Jerusalem, not too far from Method M. Get your falafel spiced to your taste. Cardamon, curry, chili and – ugh – cinnamon flavors. No longer is the falafel maker master of what goes into your pita. And you know what, he looks pretty happy about it. No wonder, he charges more than his competitors.

User manuals, reference guides and the rest of the technical documentation business has been run much like traditional falafel makers manage their stands. Tech writers create and control all content. This top-down paradigm has made us masters of our manuals, but maybe it bears review in light of the success of Four Flavor Falafel and so many “Web 2.0” businesses.

Wikis for technical documentation are one way of inverting the content pyramid. Opening up contributions and editing may make a lot of sense if your product has an active user community. You can harness the power of a wide group to create more content that users want. Do you lose control? To some extent. But remember the falafel maker who opened up his top-down hierarchy and improved his bottom line.
Katriel

Working on training my own writers in writing as little as possible, and having that little extremely focused on user needs, we developed an in-house course called Bare Bones Communications. 

The syllabus is now posted on the web — and comments are more than welcome.  One of the goals is to help reorient writers moving, or thinking about moving in the future, to DITA or other topic-based authoring approaches.
Katriel

The Claim: Everything takes longer with DITA

Over coffee this week I heard the complaint “everything takes longer with DITA” from a tech writer at a company that recently converted from unstructured FrameMaker to DITA. Why? Well you just can’t do File Open, add a paragraph or two, and consider your update done.

The Facts

The complaint may well be absolutely true – for the writer at the moment at the time of adding a paragraph. But it is absolutely false for the total document cost because DITA enables:

• Delivery of the content to the user in multiple instances (e.g. troubleshooting, installation, FAQ, etc.).
• Customization of the document for presentation to different types of users.
• Easy updating of the content.
• Definition of related topics (tasks that must be performed in a sequence, for example).
• Focusing information on what the customer needs at a particular moment (how-to information, for example, or reference content).
• And, of course, lower translation costs and much, much, much more.

The Bottom Line

Granted in some cases the productivity of technical writers may drop when writing a first draft, especially in the early stages of learning a new tool, but the total document cost will drop with DITA. Go for it!

Katriel

OK. So you made a document wiki. But how do you get subject matter experts to contribute? After all, in Wikipedia only a fraction of viewers ever contribute, but that fraction is still a very large critical mass (As of November 2006, Wikipedia receives 200,000 edits a day). This post was motivated by an off-line correspondence with Anne Gentle about motivation for contributors. Anne’s blog Exploring Information Design and Development has many useful and well-written posts about DITA, Wikis and other topics.

So How Does Your Document Wiki Reach a Critical Mass?

You probably don’t need anywhere need 200,000 edits a day – or even a year – for your Wiki to reach a critical mass that it will be interesting enough to attract and retain viewers. But you to need to attain a critical mass. If your users think that most of the reference and how-to information that they need is found in on-line help, your technical document Wiki project will fail.

Incentives, Incentives, Incentives

You could rely on the good will of your subject matter experts to contribute to the Wiki for the common good. Or, you could recall that 20^th century efforts to replace personal incentives with altruistic “from each according to his ability, to each according to his need” resulted in the deaths of tens of millions from repression and famine under Stalin and Mao.

In the academic world, recognition for contributing knowledge (typically measured by publications) comes in the form of tenure, increased research grants, and – of course – enchanced social status in the community.

A brief and readable academic study “Why Do People Write for Wikipedia? Incentives to Contribute to Open-Content Publishing” by Andrea Forte and Amy Bruckman of the Georgia Institute of Technology, describes what incentives work for Wikipedia and provides important lessons for any organization who wants to ensure the success of their own Wiki.

Bottom line: you need to provide incentives.

What Can You Do to Provide Incentives for your Company Wiki?

One approach is just to close down alternative venues. No more RoboHelp, Flare, or WebWorks conversions from Word or FrameMaker. This approach is likely to work for your technical writing staff who, after all, have to put their output somewhere. But, it is unlikely to work for subject matter experts (SMEs) – the engineering, implementation, support and management whose inputs we want and need to reach critical mass.

For SMEs, I suggest recognition. First and foremost recognition. In any organization, but especially in large organizations, ambitious staff need to keep their face in the public view to advance.

• Topic pages should identify contributors and editors.
• User pages should provide metrics for contributors (e.g., started X topics, contributed edits to Y topics, offered Z edits over the last year).
• Topic pages or user pages should offer contributors the possibility of including their picture, real name and/or contact information (e.g. Jane Doe, implementation mananger for new customers in Slovakia.)

Katriel

In response to “It takes a confident technical writer to ‘let go’ and open up his or her documentation to Wiki” in a previous post I have been berated for not mentioning that you can configure most Wikis to allow select users to add/edit content. 

So, for clarity:  

• You can configure most Wikis to allow select users to add/edit content. 
• For example, you might want to allow the tech writers, product managers and CTO write permission.
• For other users, the Wiki functions much like a regular on-line help (except, of course, you can enable users to add comments, view other comments, and you can exercise a lot of control over the look and feel of the Wiki.)

Katriel

“Google is not a search engine. Google is a reputation-management system.” – Clive Thompson in Wired (March/April 2007).

Think about how your company appears in Google – and if you can leverage tech documents to improve your Google ratings. As an example, let’s take a company called HumanEyes that offers “software for producing visual 3D and lenticular effects.”

Googling for lenticular printing yields just one result for HumanEyes in the top 10. You guessed it – a page from tech docs posted to the web with useful information about lenticular lens types. Kudos to the authors at HumanEyes!

When deciding if tech documentation will be posted to the web, factor in the influence on the Google “reputation-management system”. Tech writers – start planning on-line documentation for maximum effect on Google rankings. And when you succeed, show management (before annual bonuses are calculated)!
Katriel

Tom Johnson of Tech Writer Voices has setup a directory of technical writer blogs.  This is an excellent resource.

By the way, Tom has both Tech Writer Voices (a podcast for technical writers) and I’d Rather be Writing (a blog for technical writers, with lots of neat ideas and useful links).

Systematically preventing errors in published documents is the subject of this post.

Comments, revision marks, embedded questions, internal product names, and other content not meant for general publication have been a major pain point for Word users.

Word 2007 provides the Document Inspector – a tool for preventing distribution of the content that you don’t want to share.  In addition to the out of the box routines provided by the Document Inspector, Word 2007 enables creating new inspector modules that meet very specific needs – your needs – using the “DocumentInspectors” collection type.

If you are using an earlier version of Word, the good news is that you can use VBA to create tools that mimic the functionality of Document Inspector. Ahem, ahem — get ready for a bit of shameless self-promotion — you can also  get ready-made Document Inspector-like functionality for earlier versions of Word –from Method M. For more, download the article about systematically avoiding document gaffes.
Katriel

Once way to look at Wikis is as a replacement for traditional documentation released in sync with versions.  This may make sense quite often. 

Another way to look at Wikis is as a way to do collaborative documentation.

Following a line of reasoning suggested by David Weinberger, in many cases it makes sense for tech writers to post drafts of the docs they’re working on themselves (non-collaboratively), using the Wiki infrastructure to open up the drafting process — getting comments/additions/changes from whoever edits the Wiki oontent.  In this scenario, the tech writer still “owns” the content, but leverages the collective wisdom/inputs of a larger community to improve his or her deliverables.

Following the previous post on Wiki’s in documentation, and some off-line discussions, here is Reichman’s Rule for When Wikis Work for Technical Documentation:

1. Trust.  High degree of trust that people who edit the Wiki will not sabatoge or contribute nonsensical content (or worse).
2. Tolerance.  Many contributors and editors mean that the quality of the writing will not be perfect and will not be consistent.  Our take — don’t worry about it.
3. Critical mass.  If the number of contributors/editors will be very low, then a Wiki will not pick up the critical mass to attract users.
4. Incentives.  What incentives to developers, users and other staff have to contribute to the wiki?  If the answer is none, they won’t contribute.  Make sure to build-in incentives.
5. Confidence.  It takes a confident technical writer to “let go” and open up his or her documentation to Wiki. If you think that the best way to function in the workplace is keep your head in the sand and take no chances, then don’t do a Wiki.
6. Medium to low critical path.  If the cost of an error is very high, I’m not sure that Wikis are a good idea.  Of course, the error might be caught and corrected, but if we are covering nuclear power plant operation or brain surgery we don’t want to leave open this window of opportunity.

More to come on Reichman’s Rule for When Wikis Work for Technical Documentation – but looking forward to reader input here.

Katriel

Wikis are great.  So, when and if will using a Wiki for documentation makes more sense than having tech writers create documents with an old fashioned publishing hierarchy (the TW owns the documents, proofreads all the documents, and releases in a publishing cycle)?

My good friend and colleague Yitzchak Gale suggests that in commercial software development environments the incentives for keeping up a Wiki generally aren’t available:

“In a typical commercial software developent environment, I have found that it is difficult to get a good documentation wiki going. People are focused on getting done what they are required to do, so they do not devote enough mind share to the wiki to make it work…. In contrast, almost every free software project uses a wiki of some kind as part of its documentation, and some rely entirely on a wiki. In free software, the measure of success is how much you can convince other people that what you are doing is important and interesting, and get them to join in.”