Documentation Systems and Services
Of all the services and information that IT professionals provide to their customers, managers or end-users, none is as essential to success as documentation—except perhaps for other work products that must be delivered to fulfill or complete project work. Because this kind of output is crucial to successful completion of contracts, delivery of work products or services and so forth, it’s worth any IT professional’s salt to know something about this topic. For those professionals whose job is to share their industry knowledge or who conduct investigations, research or analysis, documentation may often be the only “product” they produce. This makes its importance entirely indisputable!
The key elements that give value to documentation are clear: providing records, documents and supporting information to enable future reference and access to all kinds of information. Please note also that documentation is of particular significance to those who create software, systems, hardware or other computer-oriented information or services. In fact, it’s arguable that those who provide any kind of information or services to third parties must use documentation (or some form of tangible information delivery) to transfer their data to the intended recipients or users.
Basics of Documentation
Having now established that IT professionals should consider documentation—especially written communications—an essential part of business practices and operations, several issues immediately emerge:
- To be effective, IT professionals must possess basic writing skills. The better those skills, the more work opportunities they enable. A corollary is that those whose skills are not so high must involve other professionals (or service providers) to enable or facilitate written communications.
- Basic word-processing, outlining and reporting skills are part and parcel of what IT professionals do. Here again, developing such skills and knowledge must be a priority for self-training and development or it will be necessary to retain and involve others to handle such tasks.
- Understanding documentation requirements, including organization, content, scope, time and effort required to create written materials as needed, is key to a successful career. This goes beyond word-processing and writing skills, requiring knowledge of best practices, various types and purposes of documents and a keen appreciation of the time and work involved in creating effective, usable documentation.
- Finally, each project or activity usually requires various kinds of documentation ranging from progress reports and time sheets that document work performed and time expended to a variety of project or activity reports that may involve written reports, communication of results, analysis and so forth. Larger, more complex projects or activities may involve delivery of entire documentation systems that include not only content, but also related Web sites, help files, update mechanisms and life-cycle planning to keep records synchronized with related systems, products or services to which such documentation speaks.
This last point helps explain why documentation sometimes involves considerable technology and systems implementation, above and beyond the effort involved in crafting content, reporting results and providing information in an appropriate form.
Documentation: Outsourced or In-House?
Depending on the amount of time and effort involved in providing documentation, and the availability of staff and resources to complete this work, it may sometimes be necessary to subcontract documentation to third parties. When making this decision, it’s wise to ponder long and hard on the centrality of documentation to your business goals and needs. That’s because in situations where documentation is the primary (or only) product, it’s risky to put so many eggs into somebody else’s basket.
Consider the implications of losing access to the knowledge and abilities of a trained documentation person or group—then ponder the potential pitfalls that poaching competitors might cause in such a situation! To some extent, these matters can be addressed with non-compete clauses and the like, but exposure to loss of key knowledge and expertise is possible when you outsource documentation entirely to third parties.
That said, numerous companies and organizations provide ready access to a broad range of documentation services. These range from placement of writers on site within project teams to complete turnkey documentation systems including content, help files, training, maintenance and related services across a project’s entire life cycle. Recognizing that the right kinds of writing skills or experiences may not be available from one’s own staff for all projects, to outsource or not to outsource is no longer really the question. In this case, the real questions become “Who?” “How much?” “How soon?” and so forth. Table 1 provides a list of documentation service providers you might find useful and interesting.
Exploiting Documentation Technology
For those who choose to create their own documentation, there’s a lot to be said for bringing appropriate technology to bear. Be it a relatively simple suite, like Microsoft Office or Adobe FrameMaker, or more complex systems that include content management such as Apache Cocoon, development and publishing such as Midgard or the Open Source Zeus documentation system, you can leverage considerable system capabilities to build and maintain project documentation. Table 2 documents various tools and technologies upon which you can draw to manage creation, formatting and delivery of documentation.
The application of technology also requires the development and use of considerable in-house knowledge and expertise. Although this laundry list may be overkill for small, less complex projects, large-scale documentation requires familiarity with all topics mentioned—and more:
- XML and XSL design and implementation: Today, even tools like Microsoft Word and Adobe FrameMaker (not to mention almost all high-end content creation or management systems, documentation tools and publishing systems) make use of the extensible markup language (XML) to describe and capture content along with the extensible stylesheet language (XSL) to transform XML documents into HTML, PDF or other intensely formatted forms for delivery to users onscreen or in print.
- Content creation, management and maintenance: Formal methodologies to design and capture documents are now available so that high-end packages support these things explicitly. Likewise, controls to manage review, approval and release cycles are also available, along with revision scheduling and management capabilities on the back end of the life cycle.
- Document delivery: XML and XSL enable “write once, publish many ways” technologies, but specifying and managing publishing formats, vehicles and schedules requires additional planning and effort. Look for high-end systems to support such capabilities explicitly and directly (whereas lower-end systems include little or no such facilities).
Doing Due Documentation Diligence
Whether you outsource project documentation or do such work in-house, the more you invest in quality and value, the more likely you’ll be able to satisfy your consumers’ needs. For those who invest in documentation technology, a willingness to spend time, money and effort creates opportunities to repay that investment with improved documents, automated management and life-cycle tools and better controls over content and delivery. We hope you’ll can take advantage of these technologies—even if only indirectly by contracting with professional documenters or documentation services—and use them to add to your bottom line.
Ed Tittel is vice president of IT certification at iLearning.com an