If you are in an organization that values project management, you likely have processes that allow you to plan, manage, and deliver documentation and online help required to support a product release. Defining the set of deliverables then becomes a required component of the planning process. As adjustments are made to the overall project plan, keep the list of documentation deliverables updated and inform affected groups of the change. This is particularly important if a change management process is not available to you. 

In addition to customers, groups within your organization may be adversely impacted by a change in the set of documentation deliverables packaged with a product release. For example, sales people may not be able to describe feature functionality, front line support may not be prepared to take customer calls, deployment teams may not be able to install and configure the product, and training may not be able to create instructional materials. Communicating a change in deliverables sooner than later will allow affected parties enough time to assess impact and implement a contingency plan, if necessary.

This is particularly important in organizations that use a reactive model or follow loose project management. In these scenarios, you may struggle to deliver documentation on an ad hoc basis. To offset the difficulty of identifying a finite set of deliverables for a future moment in time, maintain a list of deliverables that best reflects the data available to you today. Share this list with the project team and any affected parties whenever enough data changes that requires you to modify the list. Be prepared to correlate the data changes with your list, which may have the additional benefit of demonstrating the high cost of late cycle product changes.

Consistently avoiding surprises will help establish the documentation team as a reliable, organized, and well-managed member of the project team.

I couldn’t help but smile at the instructions telling me to press the red button when only two green buttons are available. There are a number of lessons we can learn from these simple instructions on a simple device with a simple interface:

• Use the product. It’s possible that the person who wrote these instructions never saw or used the machine. If you receive information second hand about how a product is supposed to work, make every attempt to validate the input yourself.
• Always test documentation on the final build. One of the major reasons a mismatch occurs between the instructions and the product is because of last second changes. Whenever possible, allocate the appropriate time to verify consistency between the documentation and the final build/version of the product.
• Be proactive in driving quality in the product interface. The instructions indicate the buttons were intended to be red and green. In many cultures, the red/green color combination indicates a stop/go action or activity. In this case, there is no correlation between the colors and the actual activities the user will perform (which are more like “go” and “go further”). If you familiarize yourself with the intended use of a product, you can use your experience to help improve the interface.
• Establish a relationship with the interface designers and implementers. The labels on the buttons indicate that there may have been a last second attempt to compensate for the lack of color differentiation in the plastic buttons. Depending on the rigidity of processes in your organization, implementors may be allowed to make interface changes late in the development cycle. Being a visible and active participant of the project team will increase the likelihood that you will be notified when this occurs.

Be cognizant of instructions around you. We can make the world a more user-friendly place - one toy crane machine at a time.

Remarkably, this solution is free. Could this be the future of translation? It certainly appears to be very promising, especially if the open source community contributes.

You can read more about this solution on the GlobalSite website. They also have a demo.

1.  Generate a pdf (or some editable, shareable format) of the updated text with commenting turned on and make it available to stakeholders.

2.  Share the contents via a document management system, ftp, or file share link to avoid filling up mailboxes and ideally to track access.

3.  Consider providing a printed copy to staff members who you know prefer to do their review/edits in print. Be sure to include the due date on the top of the paper print out.

4.  Clearly indicate portions that are new or have changed since last review/published release.

5.  Clearly indicate portions that are highest priority for specific stakeholders. 

6.  Communicate deadlines for commenting on the distributed version clearly and firmly.

7.  When deadline arrives, communicate what reviewers should do with partially reviewed contents or if they haven’t started.  Can they have overnight, the weekend on an extension?  Should they send you any comments they do have?  Should they simply sit tight and review the next iteration?

8.  Make it clear when the final review iteration has arrived.  Last Chance Texaco warnings often get more notice and higher priority.

9.  As you get closer to final version and only small portions of the text change, perhaps just send out the updated paragraph rather than the entire section/chapter/guide.

10. Have separate conversations with the critical/key stakeholders to make it clear you want their buy-in and review.  Ask what it will take to get it done: Scheduling time? Talking through it?  Etc?

11. Be sure to include symbiotic reviewers - people like support, consulting services, perhaps even “friendly” partners or customers in the review process.  They have a vested interest in quality documentation.

12. Make it clear what the process will be for corrections/updates to the various documentation components post ship.  For example, if the PM waits until after ship to provide input on the administration guide, those updates may not get in until the next service pack.  This could impact users, support, consulting services, and partners for a whole year.

13. Clearly communicate any soft/hard stats you have about the documentation - how many times it was downloaded, requested via CD/DVD, requested in print, how many guides will be updated/impacted per planned release, total page count, total # of images (if any).

14. Get senior management buy-in, and if possible, request that providing documentation review feedback be part of the MBO (management by objective) or bonus criteria for your key stakeholders.

15. Warn reviewers the business day before the deadline.  If possible have the deadline be at close of business so reviewers can at least prioritize for that last day.

16. Don’t forget to thank your reviewers and make it clear that you considered their input - even if it didn’t make it into the text verbatim.

Things to Avoid!

1. Do not send out iterations between communicated deadlines - it frustrates reviewers who are only half-through the last version and causes confusion.

2. Do not threaten or publically embarrass or cajole stakeholders who have not yet reviewed.  Talk to critical reviewers privately.

3. Do not send out huge, mass emails - if you have a large reviewer pool send out emails to logical groups by department, role, or relevant content being reviewed.

4. Do not send out low priority contents for review before high priority ones.  Always prioritize for your audience and segment them by topic if possible.

5. Do not send attachments that are going to overfill email inboxes. 

6. Do not lose heart.

There is no sure-fire way to win over the needed time in the busy schedules of development, product, and marketing manager, but these tips can help you get the most leverage out of the minutes they can dedicate to reviewing your hard work.  Please post any additional suggestions as comments!

Regardless, many mission critical applications have successfully transitioned to a SaaS model. I’m excited to see single sourcing now available in this format. Here is the press release from DocZone:

Audubon, PA – January 20, 2010 – DocZone by Really Strategies, Inc., the industry’s first award-winning software as a service (SaaS) XML content management system, delivers multi-channel output from single-source content at an affordable rate.  DocZone Publisher offers publishers an all-inclusive web-based editorial and production system that supports the creation, management, translation, and single-source publishing of content.

“DocZone offers automatic ‘push-button publishing’ to print, web, and E-book formats. Our subscription-based pricing models provide a very affordable alternative to publishers with tight budgets,” stated Dan Dube, senior vice president of sales and marketing at Really Strategies, Inc. “One of our customers reported a reduced time-to-market by 50% while increasing translation capabilities by publishing to more than 30 languages.”

DocZone Publisher offers CMS functionality in one system and provides out of the box support for high-end XML-based composition to PDF, HTML, EPUB, online help, and MS-Word formats.

To learn more about DocZone, or to schedule your demo, please visit http://www.doczone.com/.

http://webworkerdaily.com/2010/01/14/google-wave-whats-it-for/

Wave is Google’s answer to “online collaboration and communication,” but it’s still in active development so you can sign up and hope for an invitation or ask someone who’s already using it to invite you.

Watch Google’s video introduction for more details:

http://wave.google.com/help/wave/closed.html

If you have a license for Adobe FrameMaker 9, there is a free plugin available to help with this process:

http://www.adobe.com/support/downloads/detail.jsp?ftpID=4357

1) Disciplined - writers are like distance runners.  You should have evidence that the candidate writes regularly and consistently, regardless of the climate and various external factors (budget, morale, work-load).  There is much to be said about someone who can shut-up and write without a lot of drama or excuses because there are always plenty available in the technology world.  A writer needs to tune out all of the surrounding noise and focus on banging out the content at the keyboard to consistently produce technical guides.  There is also the review and revision process.  It takes discipline not just to get a first version together, but also to revise the text to a higher-level offering.  It is a painful process to re-open a document and mince words to the satisfaction of product management, marketing, and engineering.  Only a writer with discipline is willing to work through multiple iterations of text and regenerate the pdf again and again.  Leading interview questions to capture candidate’s level of discipline:

• How often do you actually write? 
• What conditions/time of day/etc make up your ideal writing environment? 
• What is the first thing you do when you get into the office in the morning?
• How do you know your text is ready for a review? 
• How many reviews/revisions do you usually endure?

2) Organized - being organized is not just about a clear desk.  As technical systems have gotten increasingly complex there is a need to be able to properly organize large volumes of interrelated steps across documentation sections as well as separate guides.  With little guidance from others, the technical writer is left to decide the proper order of steps as well as how to divide them between mandatory and optional, initial set-up vs. maintenance, and basic vs. advanced topics.  While these decisions may seem unimportant, they can make a mess of an otherwise straightforward process if put into the hands of a disorganized planner and thinker.   There are frequent jokes that users never read the docs, but the docs are in fact used and often at critical points in the installation and upgrade process during a time-limited system maintenance window.  Normally, the user turns to the documentation as a last resort, because he or she has exhausted all other means of guidance or the support line is unavailable.  (Maintenance windows are always during off hours.)  The frustrated and isolated user expects these documents to be well put together and direct them quickly to the relevant section and address their needs.  Since you, the manager, do not want to be brought in for every decision about the organization of the guides, you must hire someone who will be able to consider the ramifications of their text organization and provide the structure that is appropriate to your users.  Leading interview questions to indicate how organized the candidate’s mind is:

• How do you approach an assignment?
• At what point do you consider the TOC, Index, etc? 
• How do you decide what content belongs in the appendix? 
• Have you previously been responsible for designing a complete set of guides?
• When fitting new content to an existing text where do you start?
• Do you get input from users?  How do you collect that input?

3) An Active Listener – writers must interview many different resources repeatedly to get the level of detail required for proper documentation.  A good listener will be able to pull together the information that was provided by technical resources and assemble it into a proper guide, but it requires an inquisitive, active listener to get the level of detail necessary to provide good documentation.  Tenacious listening perhaps is best.  That means not accepting the information from the technical expert because they are so wise and impressively obtuse, but actually comprehending and questioning the information provided.  It’s important the candidate can do this in a polite and calm way or they will be shut out of future information exchanges.  With a degree of finesse and respect the candidate must be able to push through the initial level of detail to one that will allow the final documentation to stand on its own.  This will prevent any last minute delays just prior to shipping because a documentation gap is found at the eleventh hour.  It will also reduce technical support investment and engineering escalation hours down the line due to reduced call center volume.  Leading interview questions to determine the candidates listening skill level:

• What do you bring with you to technical information exchanges?
• When was the last TOI (Transfer of Information) session you attended? 
• What questions did you ask? 
• Did you follow-up with any prior to submitting the draft for review?
• How do you pursue complex topics with subject matter experts?

4) Battle Scarred – good technical writers are in the fray.  No technical document should be written from the design spec or marketing requirements so the writer themselves must be battle scarred from installing and reinstalling pre-release software.  It is not enough to describe the behaviors of the product, but the writer themselves must have stumbled through the processes without much of a guide in order to write a text that will benefit the reader. Only a writer who actually uses the product will be able to delve into the context and provide the user with the information required to make important configuration decisions.  Everyone has read documentation that stated only the obvious and provided no background on the ramifications of the setting, “Check the selection box to enable advanced language analysis.”  Only a writer who cares enough to question and actually play with the settings will explain in the documentation why a user may want to have “advanced language analysis” on or off.  Leading interview questions to gauge how hands-on your candidate is:

• On your last project how did you get access to the product you documented? 
• Have you ever started an installation manual from scratch? 
• Where did you start? 
• How often did you have to re-install?
• Did you get build notices?
• How many bug reports did you file against the last release you documented?
• What were the late changes you made to the documentation as a result of product updates?

While all around experience is definitely a factor as those who have managed to live on their technical writing skills clearly have chops, I encourage you to include these additional skills in your selection process as they will reduce the ‘hands-on’ time you’ll need to invest as a manager and provide a much superior documentation set.  I have had the pleasure of working with several highly effective technical writers and these four traits are not only common, but also very strong in each of them.

The cost of translating documentation is frequently the largest expense of a technical writing team. Dr. Schwenk offers tips and tricks to help control these costs.

I have added his blog to our Links page. His blog is available here.

Read the full article here.