Accelerated Authoring™ @ Method M

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

In a previous post we talked about Accelerated Authoring™ as a collection of tools and methods to enable improved productivity for knowledge workers. Content controls are part of the Accelerated Authoring collection and are the subject of this post. Specifically, we will talk about using Content Controls to create highly formatted documents.

Most companies have multiple series of documents – say case studies or application notes – that will be prepared over time. It might be a good idea for the first one in each series to be prepared by a graphic designer (or at least by a team member with design skills).

In practice, keeping the design from slipping over time as writers and subject matter experts edit documents in the series can be challenging. Inadvertent clicks tend to cause images to move, alignment to be lost and other changes that result in:

• Design deterioration – documents have a less consistent and less professional look.
• Time and energy lost in trying to get back to the original formatting.

To read more about Editing Highly Formatted Documents in Word – and how Content Controls can be used as part of a complete methodology for enabling staff to create and update highly designed documents, download content controls and making beautiful documents.

Look for the next post about anticipating and preventing document gaffes (proactive document quality). Katriel

Reasonable folk might disagree on how to improve the productivity of workers who spend hours each day working with a word processor, but there should be general agreement on the following list of goals:

• Spend less time formatting documents, and more time creating value.
• Produce documents that are more readable and more aesthetic.
• Enable easy reuse of content by:
  • Copying and pasting between documents and from documents to e-mail.
  • Reusing blocks of information between and within documents.
• Easier to update documents.
• Easier to find content in documents.
• Provide “just enough” information in documents.

Accelerated Authoring™ is a collection of tools and methods to enable attaining these goals. Content controls are part of the Accelerated Authoring collection and are the subject of the first post in the Accelerated Authoring series.

To read more about Accelerated Authoring™, which is an important part of structgured authoring, download: Find out what structured authoring is and why it matters.

BTW, Accelerated Authoring™ is a trademark of Method M Ltd.