by Liz Fraley
This is the fourth of a series of articles based on the talk I gave at the Content Management 2005 conference. These articles focus on extending single-sourcing systems and activities to integrate content-generating organizations enterprise-wide.
How Does Engineering fit into Single-Sourcing Plans?
Auto-generate Content from Engineering Systems
A lot of content is locked up in systems that are traditionally engineering systems. What if you could auto-generate content for particular kinds of technical manuals directly from engineering systems?
Release Notes are tightly tied to bug-tracking systems. Release notes document which bugs have been fixed and which are outstanding. And for the most part, bug-tracking systems contain the basic data from which release notes are constructed. Is the bug fixed? In which release is it fixed? Is it internal-only or does it affect public-facing features? Automatically generating anything from the bug-tracking system is better than having an author manually copy-and-paste bug information on a one-by-one basis.
Request and feature tracking tools provide more information to release notes, white papers, and product specifications. A good feature-tracking tool is already tracking individual features against specific releases. In which release is this feature planned? In which release did this feature actually appear? We can automatically generate a list of features that were completed for the current release and drop the entire set of information into the larger Release Notes document.
This way, writers start with partially-complete documents not blank documents and a web-view into a database. Writers need only to polish the language, add introductory and closing text, and maybe do a little re-shuffling of items. A little bit of automation goes a long way to improving writer productivity.
Produce Documents with Varying Levels of Detail
What about documents that are 80% the same but vary in levels of detail based on the audience. Inside sales people do not need — or, in many cases, want — to know how a feature works. On the other hand, the customer service technical representative needs to know exactly how it works. Internal developers need a whole other level of detail in order to integrate the next feature.
This technique is what’s called “profiling” and single-sourcing conferences are full of organizations using profiling to control translation costs. It’s a short hop to consider “varying levels of detail” as just another type of translation: you’re translating level of detail, rather than language, to meet various audience needs. From one source, you can create one document that is appropriate for external customers, one for internal developers, and one for field engineers.
Increase the Quality of Subject Matter Expert (SME) Reviews
Engineers struggle with change bars and large documents. More often than not, engineers get huge, isolated documents to review. They must search the entire document looking for the little bar indicators in the margin that identify documentation changes. And they must check every bar in every document in order to find the changes that apply to the work they’re doing.
If you have your documents in a non-proprietary format, you can present a diff view to engineers. A diff is the output of a program that displays the differences between two text files. Normal diff output shows text that has been added, deleted, or changed. By default, lines common to both files are not shown. Lines that have moved will show up as added on their new location and as deleted on their old location. It’s a compact view of difference between document versions, that gives just enough context to verify the change is correct.
This is the #1 feature engineers ask me for. Every engineer I’ve ever known has wanted to get diffs from technical publications rather than the usual change-bar filled document. Their time is already compressed, so the less work they have to do the better. And if they can quickly identify changes and context, they’re more likely to do a review, than if they must walk an entire document manually.
Improving your reviews directly improves the quality of your documentation product for end users.
Handle API Documents More Efficiently
For software that supports API documents, there are a number of ways to completely generate simple API documents.
Sun has had JavaDoc in place for years. JavaDoc is a tool from Sun Microsystems for generating API documentation in HTML format from doc comments in source code. JavaDoc documentation is a hugely popular way of handling Java API documentation. It generates the document set at compile-time.
Software engineers write the initial documentation and authors come in to polish up the language directly inside the source code. End users are thrilled to get good JavaDoc API documents, because they’re already familiar with this kind of documentation. Every JavaDoc document looks the same and divides information up the same way. Since it’s part of the code, the document is nearly free to add to your product set.
Sun isn’t alone with JavaDoc. Doxygen is an open source JavaDoc-like documentation system for C++, C, Java and IDL. Like JavaDoc, Doxygen generates files that can be easily compared automatically (remember about improving review activities). Both systems do one other thing: they directly tie documentation to specific API features.
Comparing two sets of generated docs not only gives you the difference for review purposes, but it will immediately identify new API features and features that have been deleted. So for documentation that is tied directly to API source code generation, you get automated realization of code differences and API changes — without having to rely on the relationship between Technical Publications and Engineering.
At the same time, because these documents are embedded in the source code, you open up another avenue for original content gathering. Domain experts can contribute directly to this model. Writers can polish and shape information that developers initially document.
Documents become combinations of XML units AND content from the software source code tree. The tight binding between source code and documentation, allows the writing staff to easily track changes in the code which are tied to changes in the documentation. It allows auto-generation of template documentation and, in some cases, complete documentation.
The Benefits Aren’t Limited to Software Engineering Organizations
Only technique #4 (API documents) is really limited to software engineering organizations. These same principles have implications in other industries:
|Biotech||Database/assay machine integration|
|Pharmaceuticals||Product labeling requirements|
Integrating diagnostic information with procedural documentation
How about Customer Support…
Generating Documentation from Knowledge Bases
Since we’re already talking about generating content out of business systems, what about generating content out of customer support knowledge bases (KBs). Often, customer support self-service knowledge bases are populated with content that is generated by an external KB vendor. Articles with the KB are augmented by customer support representatives based on direct interaction with customers.
Obvious documentation product targets include FAQ-style documentation. But it could just as easily include common troubleshooting guide information that is based directly on KB content and the frequency of article access. Integrating with a KB system gives you the opportunity to identify which articles generate more hits — which topics do users generally need more help with — based on verifiable, measurable statistics.
If you are also tracking article effectiveness (how well does the KB article solve the user’s problem), you have a pretty good basis from which to build a troubleshooting guide. Writers don’t need to generate this content from scratch: they have the article to use as a tangible basis, because you generated their starting document directly from the KB in the first place.
At the same time, because you’re automatically generating the initial content, you’re automatically coordinating content to guarantee consistency between KB articles and documentation written from in-house publications group.
Let’s not forget that you can get the links between (inside) documents and KB articles, and field alerts for free as well.
Get useful tips and valuable resources every month
Join the thousands who know just how much we share.