There is a decision doc managers need to make all the time: balance savings today against expenses tomorrow; balance constantly patching a doc with tearing the whole thing down and starting anew. My solution to fixing my fence was the exact same I would have taken to patching a doc.
Scrum, the new development methodology in the Agile development family, is fast gaining acceptance in software development. But how can writers, who have little or no experience in any of the incremental development models, adjust to this methodology? And, how does the Documentation Development Life Cycle (DDLC) change in Scrum?
Microsoft’s Visual SourceSafe was not created with technical communicators in mind. It was created for engineers writing software source code. But it is successfully used by technical writers in offices around the world to control documentation.
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.
In this column, I’ll review what user assistance architects mean by reuse and what its benefits can be. I’ll then describe some different scenarios for reuse and offer guidelines that user assistance architects and information developers can follow. My examples show how DITA (Darwin Information Typing Architecture) can be an effective reuse framework. But the principles I discuss go beyond DITA, and you can apply them to any structured information framework or toolset.
The topic of technical publishing is relatively new to the world of Eclipse. One can make the argument that technical publishing is just another collaborative development process involving several people with different backgrounds and skills. This article will show that the Eclipse platform is a viable platform for technical publishing by discussing how to write documents such as an article or a book within Eclipse. In fact, this article was written using Eclipse.
When you think of marketing, do press releases, brochures, presentations, direct mail, and web sites come to mind? Those pieces are certainly parts of the puzzle.But a lot must go on behind the curtain to make those on-stage pieces worthwhile. These often hidden goings-on are the leadership techniques of a successful documentation manager. The result is a documentation department that warrants the effort expended on marketing. After all, marketing succeeds only if services are reliable, communication channels are open, and products meet expectations.
We have two distinct sets of users; internal product consultants and end users. Prior to using RoboHelp Server we had little way of identifying who was looking at our documentation, when they were looking at it, or how often. That has now changed.
In July, in a sharp break from tradition, the Army began encouraging its personnel — from the privates to the generals — to go online and collaboratively rewrite seven of the field manuals that give instructions on all aspects of Army life. The program uses the same software behind the online encyclopedia Wikipedia and could potentially lead to hundreds of Army guides being “wikified.” The goal, say the officers behind the effort, is to tap more experience and advice from battle-tested soldiers rather than relying on the specialists within the Army’s array of colleges and research centers who have traditionally written the manuals.
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.
The non-writer who takes over the documentation can act like a bull in a China closet, copying and pasting from Word, mixing styles, not understanding the setup, basically wrecking the consistency, the bullet levels, the formatting. If you see the documentation later and find that the client has added steps without numbers, included text that breaks every rule in the style guide, won’t that be unnerving? Yes, it will make you want to jump out the window.
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.
The way in which we compute has been changing over the last three or four years. In fact, I think I can safely say that what many people are doing now isn’t computing in the traditional sense of the word. And this move is going to have an effect on technical communication.
This chapter explores the idea that a small group of people who have a sense of belonging in an online community may provide content much like a technical writer does. Regardless of their background, education, or training, more people are becoming providers of technical information on the web.
Software products have found ways to share content and reuse content to deliver more value with limited resources. For example, fantasy football web sites share player news, injury reports, and game statistics. Security products often reuse security announcements and warnings from trusted sources, and present them as rebranded content. We are also seeing software vendors using Twitter and RSS feeds to distribute information and announcements. The next step is when these information feeds are integrated into the product user interface itself, making it the one stop resource for all the information needs of its users. No more need to use google when your product itself delivers the answers to all your questions from the sources you trust.
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.
If you need the collaborative aspects of a Wiki combined with DITA's modular topics and publishing capabilities, then DAISY might just be the system you need--and it's free. DAISY provides WYSIWYG editing for Wiki pages that can be combined to publish books, either in a PDF or as a single HTML page.
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.
Sometimes our developers are just a bit too eager. It doesn’t happen that often but when it does, it takes us Technical Writers by surprise. One such occasion happened today when the first build was created for the next release of one of our applications. No real issue there, but when they came to us half an hour after the build process completed to say the help didn’t look right, we went to investigate.
The reasons for the White House's decision to run its Web site, whitehouse.gov, on the open source content management system Drupal are being discussed on various Web sites. Alongside Drupal's functionality, flexibility and openness, some are suggesting that Drupal's documentation was also a key factor for deciding to use this system.
Collaboration happens when multiple people work simultaneously towards a common goal. Collaboration software are tools which try to make working together easier and more productive. There are hundreds of methodologies and approaches out there to collaboration. We want to bring the focus on one particular dimension: open vs. structured collaboration.
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.
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.
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.