Accelerated Authoring™ @ Method M

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

Last week had the chance to a colleague who just converted thousands of documentation to DITA. They had a budget for converting thousands of pages of existing unstructured FrameMaker content to valid DITA XML, but no time or resources to rework the content into concept, task and reference chunks. So, was the conversion to DITA worthwhile?

The resounding answer was “yes”. Here’s why: immediately they can easily reuse topics and produce to customized outputs for very specific needs just by editing the DITA map.

Next post: Does Everything Take Longer in DITA?
Katriel

Productivity — when you think about topic-based authoring, think of the productivity gains.  Writers work faster and better when presented with a fill-in-the-skeleton, and when they don’t worry about look and feel.

Reuse, consistency, the ability to create custom documents for readers are all big factors in deciding to move to topic-based authoring.  But don’t forget productivity.
Katriel

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