An Overview of Single Sourcing with an XML Content Management System

Creating an XML-based Content Management System to single-source technical publications is as simple as 1 - 2 - 3. OK, maybe it isn't quite that easy, but this article discusses how it can be done.

Sapir, Rick. KeyContent.org (2004). Articles>Content Management>Documentation>XML

A Case of Exhaustive Documentation: Re-centering System-oriented Organizations Around User Need    

Braun Corporation's home-grown documentation processes served the organization well for its first 50 years as it grew from a local to a nationally-competitive producer of mobility and accessibility products. Now poised to become a global leader in its field, this corporation found its efforts hampered by ineffective and outdated documentation practices, which were hurting the company's competitive advantage. This article describes Braun Corporation's curious mixture of global reach and local isolation. By bringing in a technical communicator with expertise in user-centered design, Braun has begun reforming its formerly exhaustive documentation and communication practices. While technical communicators have incorporated a variety of strategies to develop user-centered and task-based documentation, less attention has been placed on changing the cultures of these organizations. The case presented here represents a shift from establishing documentation procedures to critically assessing and reforming existing procedures for the global workplace, describing the shift from ineffective and exhaustive processes to effective processes with defined goals and measurable outcomes. The article concludes with an inventory for determining whether other organizations are over-documenting processes and products, and offers suggestions for creating better documentation procedures.

Salvo, Michael J., Meredith W. Zoetewey and Kate Agena. Technical Communication Online (2007). Articles>Documentation>Management>User Centered Design

A Case Study in Developing Dynamic Content at Ontario Systems

Charles Cantrell, an Information Engineer, describes Ontario Systems' process for delivering dynamically assembled and populated documentation for Artiva, its 'highly customizable' accounts receivable management application.

Cantrell, Charles. Rockley Bulletin (2004). Articles>Documentation>Content Management

Customizing the Appearance of Your Manual, Help System, and HTML Help System  

Doc-To-Help gives Help authors complete control over the look, feel, and content of a project's printed manual, Windows Help system, HTML files, and HTML Help system. Maintaining different content is controlled using Doc-To-Help's conditional text feature, which allows authors to mark content for print-only, online-only, WinHelp-only, and so on. In this article we discuss how you control the appearance of the printed manuals and Help using Word templates, and HTML output using cascading style.

ComponentOne (1999). Articles>Content Management>Single Sourcing>Documentation

Dealing With an IT Scourge: Process Documentation  

In this article, we outline how IT analysts can effectively make determinations about the value of process documentation, and in the process, transform a potential scourge into a possible blessing.

Schiesser, Rich. TechRepublic (2005). Articles>Documentation>Programming>Project Management

Developing a Project Life Cycle for Technical Publications  

Having a technical publications project life cycle (pLC) that parallels an organization's product life cycle (PLC) greatly facilitates its adoption by engineering or development organizations. A technical publications project life cycle relates major documentation project management strategies, tasks, and deliverables to the same model used by technical organizations to control product development in an efficient and cost-effective manner. Some technical organizations perceive the documentation development process as being “intrusive” into the product development process, particularly during the Implementation Phase of the PLC. Communicating a technical publications pLC to these organizations early in the PLC eliminates this misperception.

Le Vie, Donald S., Jr. STC Proceedings (2003). Articles>Documentation>Project Management

Document your Database Project to Capture Relevant Info

Documenting a database during its development is a best practice to ensure that the organizational schema, data objects, and other related information are captured for future reference.

Kelly, William T. Builder.com (2003). Articles>Project Management>Databases>Documentation

A Documentation Database for Managing Time and Costs  

Keeping track of a technical writing team’s time can be a tedious task, especially when that time has to be charged to various internal departments. Using Lotus Notes™ (Lotus Development Corporation and Iris Associates, Inc.), we developed a relational database to track this information. This database uses a single form for all documentation status inputs. Then it summarizes the data in a variety of view. Separate forms track SEI statistics and simplify department employee time administration.

Lang, Darice and Debra Ricks. STC Proceedings (1994). Articles>Documentation>Project Management

Documents That No Project Cannot Be Without

Short deadlines force project teams to quickly design, test, and release the product with little or no design documentation. If these documents are written, they generally are not well-written and are not comprehensive. The fact of the matter is that most project teams do not have enough staff to design the product, let alone write and manage documentation. This situation creates an ideal opportunity for technical writers to assist the project team in more ways than writing a user guide.

Dick, David J. Carolina Communique (2008). Articles>Documentation>Project Management>Collaboration

Easy Tools for Documentation Management  

The use of three simple tools can assist the documentation manager, from start to finish, on any new project. A revamped pubs plan, a new concept with engineering worksheets, and a matrix of modularized information are all utilized with a slightly new twist. The Pubs Plan is redefined to help you launch your project with a team approach, identifying issues, and proposing solutions. The Engineering Worksheets list all the critical pieces of information your writers/illustrators need for each component of the product. These pieces of information are then tracked by completion date on an Information Matrix. These documents work together as complimentary management tools that can be easily developed and scaled to the complexity of any project.

Shumate, Chona E. STC Proceedings (1999). Articles>Documentation>Project Management

Egoless Writing: Improving Quality by Replacing Artistic Impulse With Engineering Discipline    

When technical communicators have a strong personal attachment to the publication they are preparing, this attachment may interfere with the design and testing of the publication itself. Documents developed by solo authors tend to be late, buggy, and exceedingly difficult for others to maintain. 'Ego-less' methods---collaborative and structured---break the proprietary connection between the writer and the book; in so doing they permit the most powerful tools of engineering and testing to be used. But they also reduce the satisfactions of the communicator's job.

Weiss, Edmond H. Journal of Computer Documentation (2002). Articles>Content Management>Documentation

Enterprise Agility: SOX and Enterprise Information Integration  

The intent of Sarbanes-Oxley (SOX) can be characterized as risk reduction: reduce errors, inhibit fraud, and provide shareholders with transparent equal-access to material knowledge. But implementation is principally procedural controls and documentation, under threat of penalty. The vague parts of SOX are where the real leverage lies: principles of intent, and corporate transparency.

Dove, Rick. Paradigm Shift International (2005). Articles>Knowledge Management>Information Design>Documentation

Estimating Scope and Schedule for a Help Project  

During this session, we will learn how to create a topic list to determine project scope, and then we will begin to calculate how long it will take produce all of these topics. When we’re done, you will have a methodology for doing this for your own project.

Deaton, Mary M. STC Proceedings (1997). Articles>Project Management>Documentation>Help

Estimating Scope and Schedule for Help Projects  

Three steps to a more accurate Help schedule.

Deaton, Mary M. STC Proceedings (1996). Articles>Project Management>Documentation

Estimating Time and Cost for Policies and Procedures Projects  

Estimating time and cost for a policies and procedures project can be an adventure in guessing and a ticket to grief. However, planning with a detailed checklist and list of assumptions can you help create a more realistic estimate, please your client, and protect your sanity and pocketbook.

Escoe, Adrienne. STC Proceedings (2003). Articles>Documentation>Project Management

Getting a Count: Recording Metrics in Documentation Plans  

Most large documentation departments are already using some kind of a formal documentation project planning strategy. Many are modeled after the work of Dr. JoAnn Hackos, with information plans, content specifications, and/or documentation plans (Hackos, 1994) 1 . By carefully adjusting the look and feel of the planning documents, adding room for recording actual numbers at the completion of the project, managers can implement a metrics strategy that takes advantage of existing templates and piggy-backs on existing archiving and checkout procedures.

Romaine, Garret H. STC Proceedings (1999). Articles>Documentation>Project Management

Going Online: A Case Study in the Development and Implementation of Netscape NetHelp  

Computerized Medical Systems, Inc. (CMS) - the worldâ*™s leading radiation therapy planning (RTP) company with over 1000 installed RTP systems and over 400 installed dosimetry systems - decided in late 1996 to move existing FOCUS documentation online. Reasons for this included: the existing documentation set perceived as too difficult to use; increasing printing cost; and customer feedback. Using Netscape NetHelp as a basis, the CMS documentation staff reduced printed documentation size by two-thirds while making the information more accessible. Reactions to FOCUSHelp have been highly favorable. Future plans include migrating to the NetHelp2 framework and reducing topic lengths.

Rupel, Roberta A., Ellard Douglas, Bill Bledsoe and Frank Watson. STC Proceedings (1998). Articles>Content Management>Documentation>Help

A Guide for Software Project Managers - Planning User Documentation

A Guide to the Project Management Body of Knowledge (PMBOK® Guide)–2000 Edition is the main sourcebook in the project management field. Whilst it covers Project Communications Management, it doesn't extend to user documentation. This article seeks to provide guidance for project managers as to how the user documentation process fits in with the overall project planning. It examines: the traditional way documentation is approached and how it impinges on project planning the effects of making changes to this traditional approach.

Johnston, Carol. Cherryleaf (2003). Articles>Documentation>Project Management>Body of Knowledge

How to Plan On-line and Paper Versions of a Software Manual

On projects for which you must produce both on-line and paper documentation, there are many things you should consider before you start.

Kozuma, Bruce. Boston Broadside (1991). Articles>Documentation>Project Management>Planning

Implementing a Document Control System  

Document control is a major component of any quality system. To implement a document control system, first establish Policies/procedures for generating, approving, issuing, and revising documents. The next step is to design and implement forms and a filing system/data base for managing quality documents. Teamwork and established guidelines can help ease the complexities of implementing a document control system.

Matthews, Diane L. STC Proceedings (1994). Articles>Documentation>Content Management

Improving Publication Quality Through Project Management  

A methodology for developing high-quality software developed by the Software Engineering Institute at Carnegie-Mellon University can also be applied to developing technical publications. This workshop addresses several aspects of this methodology using various project management techniques. By bringing your development process under better control, these techniques will ensure a more uniform quality in your publications.

Firman, Anthony H. STC Proceedings (1995). Articles>Project Management>Documentation

Information Metrics: Keeping Your Writing Projects On Track  

Keeping information metrics for documentation projects gives managers the ability to more accurately estimate future projects. Publications departments can develop their own tools or they can use existing tools to track such things as page size, hours-per-page spent writing, illustrating, editing, and producing manuals; and the dependencies of each manual. This kind of information can help to determine development schedules, show how late changes affect the documentation process, and accurately determine what it will take to complete quality documentation on time and within budget.

Gordon, Judy L. STC Proceedings (1993). Articles>Documentation>Project Management>Methods

Information Planning for Successful Online Documentation  

Creating an information plan should be the first phase of any publication development life cycle, whether hard copy or online. The plan is a tool for reporting the results of your research about your audience, their tasks, the market, and the product. The plan presents the basic organization and content of the publications you intend to build, effectively directing the documentation team to produce a publication with very specific goals in mind.

Stevens, Dawn M. STC Proceedings (1996). Articles>Information Design>Management>Documentation

Is a Documentation Wiki in your Future?

If we can solicit user participation in a Web 2.0 knowledge community (a volunter wiki documentation, for example), we might have a powerful means for creating high quality content. But how should this process work?

Hackos, JoAnn T. Center for Information-Development Management (2007). Articles>Documentation>Content Management>Wikis

It's In the Numbers: Using Metrics to Plan Documentation Projects

It's in the numbers. Creating documentation is not an exact science, yet as communication leaders, we are expected to provide real estimates for how much time we need to document a project, or what we can produce given a predetermined timeline.

Yundt, Margie and Sherry McMenemy. Writing Assistance (2006). Articles>Project Management>Documentation>Assessment