What happens when the software firm you work for decides it will not deliver large printed manuals any more? Then the request comes to put everything online. Six months later, user profiles shift to the World Wide Web and you're asked to deliver HTML. In the future, a database of SGML information chunks may let us deliver anything, any which way. Today, we must devise a system that allows us to 'author once, publish many'. Such as system is crucial for software and hardware documentation. The method I chose was to go from FrameMaker to Acrobat .pdf files to HTML. I wrote in Adobe FrameMaker, then converted to .pdf files with Adobe Acrobat, and converted FrameMaker to HTML files with Quadralay WebWorks Publisher. But while we're waiting for the future, just learning SGML and diving deep into DTDs alone could be a mistake. SGML is a language which sets out structure, and most of us are concerned with content. Enter Information Mapping, or information types of your own devising. Identifying chunks of information such as a procedure for changing the default printer is extremely important. If we then mark each chunk for an index and record its type and title, we've also got the keywords for a future database.
Using a modular process has proven highly effective in developing both on-line and printed documentation. This paper identifies module types and structures, discusses technical, psychological, and management hurdles, and demonstrates how this process can improve consistency and quality. In addition it discusses tools and resources, preliminary planning, preparation of personnel, and (briefly) tracking results.
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.
In the city of Konstanz on the shores of Lake Constance, Siemens AG manufactures equipment for sorting post. Also at the same location, a team of 16 experts create the corresponding technical documentation. But their work is not restricted to handbooks and CDs. Since ten years, this department, called 'Technical Media', has also been taking care of multimedia and training.
This paper tells how Lawrence Livermore National Laboratory enriched CRI's online documentation set by publishing local manuals using the same SGML DTD used by CRI and delivered using (a more sophisticated version of) the same World Wide Web server (DynaWeb 3.0). This approach supports flexible local content and styles, yet integrates local and CRI manuals through one access mechanism and user interface. We explain the basic strategy involved, compare the benefits of this approach with three alternatives, and discuss the problems to which it gives rise.
New technologies have added to the complexity of today’s documentation management. Documents have grown beyondpaper into compoundfonns that can include audio and video segments, and may exist only in electronic form. This documentation can capture much of an organization’s knowledge and wisdom. But often, these intellectual assets are lost because the organization lacks a formal knowledge management system. Many professional communicators already manage their documents from creation through delivery, but stop short of archival. This paper explains how to plan for efficient document production so that intellectual assets become available for easy retrieval and reuse.
The importance of single sourcing the long print manual is becoming less of a demand (have you handed someone a 100+page manual lately that someone accepted with eagerness? ) I predict that in several years time, we’ll see a major shift towards web-based tools in tech comm, especially wikis.
There are obvious benefits to single sourcing, the ones that roll off the tongue the minute single source is mentioned: multi-format publishing, consistency of information, quicker updates of common content, lowering translation costs and so on. But beyond all those, what else is there? In this guest blog post, Gordon McLean discusses just that.
When FrameMaker content containing Anchored Frame is imported to RoboHelp, the Anchored Frame is converted to corresponding image in generated XHTML content. The quality of generated images has been an area of concern. While some users are satisfied with the quality of images generated, others feel the scope of improvement in the image quality. This blog describes some of the best practices and workflows that will help obtain improved quality of generated images. In other words, it will allow users to maintain the original quality of source images generated through specialized image editing applications.
In agile software development you want to travel as light as possible, and the easiest way to do that is to choose the best artifact to record information. I use the term 'artifact' to refer to any model, document, source code, plan, and so on created during a software development project. Furthermore, you want to record information as few times as possible, ideally only once. For example, if you describe a business rule in a use case, then describe it in detail in a business rule specification, then implement it in code, you have three versions of the same business rule to maintain. It would be far better to record the business rule once, ideally as human-readable but implementable code, and then reference it from any other artifact as appropriate.
The other week my colleague asked me to write down a few notes about how I handle images with Flare. I realized there’s a lot to know about images, especially when trying to single source them both to print and online outputs. In this post, I’ll jot down a few of the more tricky points when it comes to single sourcing images.
When it comes to documentation projects, primarily technical, medical, and scientific, using XML is a no-brainer. The heavy thinking comes when deciding which flavor of XML to use: DocBook or DITA (Darwin Information Typing Architecture). I have been a steadfast supporter of DocBook for over six years. I'd tried my hand at DITA and gave it up as a fad; lots of bells and whistles, but too complicated to integrate. And couldn't DocBook do everything DITA promised anyway?
A small documentation team devised an innovative workflow to provide documentation for Interleaf publishing software for Windows and Motif, in English, French, German, and Japanese, using a single set of online source documentation. We used technology to streamline tasks, maximize communication, and optimize the documentation for future updates.
This article explains how we built a solution to producing sales proposals and other sales literature for our own company using an affordable content management solution.
RoboHelp now offers a rich set of features for delivering multiple customized outputs out of a single project. This article by Matthew Ellison provides some guidelines and tips on using the key single-sourcing features.