Advantages of Using Microsoft SourceSafe While Writing Your Technical Documents

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.

Technical Communication Center (2009). Articles>Content Management>Documentation>Technical Writing

Applying Web 2.0 Technologies to Technical Documentation

This article is based on my presentation at the Institute of Scientific and Technical Communicators' annual conference in October, 2006. Every now and then, there is a change in the value of what technical authors deliver. These are moments when organisations pay attention to technical documentation. This is because they recognise that these changes mean they can create something that will be of real value to the business and to their customers. In recent years, there have been three "waves of interestingness". The first wave was the introduction of Windows Help (WinHelp). The second major wave was the introduction of the Internet and intranets. This was a time when organisations looked at how they could transfer large amounts of information from paper to online. They were faced with issues such as how users could access and understand all this information easily - issues that technical communicators deal with on a day-to-day basis. I believe we're just about to approach the new wave, which we have called "Tech Writing 2.0".

Pratt, Ellis. Cherryleaf (2006). Articles>Web Design>Documentation>Technical Writing

Are We Giving Readers What They Want, in the Way They Want and Need It?

With all the talk about Web 2.0 and the attendant technologies, are readers actually being better served by documentation now than they were in the past?

DMN Communications (2008). Articles>Documentation>Technical Writing>User Centered Design

Authoring Tools Do Matter

The authoring tool does matter. Writers are focusing on the wrong set of issues (leading, kerning, print formatting), none of which is actually relevant for the output.

O'Keefe, Sarah S. Palimpsest (2009). Articles>Documentation>Technical Writing>Software

Avoid the SOX (Sarbanes-Oxley) Documentation Nightmare With These Five Tips

The Sarbanes-Oxley Act has been called the most comprehensive reform of corporate law since the Securities Exchange Act was passed in 1934. The effects of SOX are far reaching. Its provisions govern actions by management, audit committees, and boards of directors of public companies. Like it or not, Sarbanes-Oxley is here to stay. Its impact on IT departments is major and growing. The reaction of many IT groups is to document everything in sight in an attempt to cover themselves. In the end, this can be counter-productive, expensive and wasteful.

D'Amico, Vin. IT World Canada (2006). Articles>Documentation>Regulatory Writing

Baselining Documentation on a Wiki

The dynamic nature of wikis can cause a few headaches when you need to baseline documentation that's on a wiki to correspond with the release of your product. This blog post looks at some ways in which you can try baselining wiki content.

DMN Communications (2008). Articles>Documentation>Technical Writing>Wikis

Benefits of Using a Professional to Write User Documentation

Studies have shown organisations value the following benefits: overall organisation, the sales team, and documentation meets the customer's requirements.

Cherryleaf (2003). Articles>Writing>Professionalism>Documentation

Betriebsanleitungen für Anlagen  

Der Normenunterausschuss NATG-F des Deutschen Instituts für Normung e.V. ist derzeit damit befasst, Regeln zur Erstellung von Betriebsanleitungen für Anlagen zu erarbeiten.

Doculine (2002). (German) Articles>Documentation>Writing>Technical Writing

Brokedown Palace Part 2: Workflows for Fun and Profit

If you're going to toss out your user guides, you'd better have a good user interface and concise supporting materials. Workflows can help you both in the design of the user interface and in the creation of job aids for the people who use your product. A workflow is a compact and effective way to describe the flow of any procedure. How many times have you grumbled about the design of a piece of software or Web site that you've been trying to use? Chances are that no one ever sat down to model it using the workflow technique.

Knowles, Michael. Write Thinking (2002). Articles>Writing>Documentation

Case Study: Communication Problem vs. Programming Problem

In looking at my documentation, I found a couple of inaccuracies, and it’s possible that they were the direct cause of the data problem we ended up with. I haven’t verified this yet because at this point, it looks like it hardly matters (as long as I correct the inaccuracies). If my documentation led to the problem, it has led us to analyze a bigger problem that’s really at the heart of our customer’s difficulty. The discussion has been about what needs to happen in our system vs. what is actually happening. We think the programming and the data model have fallen short in some ways; fortunately, the wiring can probably be fixed with relatively little pain. It’s a matter of making sure we know what the customer wants to happen so it will be programmed the right way.

Minson, Benjamin. Gryphon Mountain (2010). Articles>Documentation>Quality>Technical Writing

Change is Gonna Come

There's a shift happening in the way in which documentation is produced. We’ve all seen the beginning of it: the growing volume of what’s called (among other things) user generated or crowdsourced documentation. That trend is growing. And while a number of people in our profession are still resistant to the idea, it’s only a matter of time before users are our main partners in creating documentation.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Technical Writing>Social Networking

Change Your Writing Style to Make Documentation More Usable and User-Friendly

When the subjects of usability and user friendliness in relation to documentation are broached, writing isn’t often the first thing that comes to mind. But it should be.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Technical Writing>Usability

Coffee and Documentation

I like the concept of not treating the readers of documentation like idiots. This little card gave me the information that I needed and couldn’t know ahead of time (how much water to use, the filter looks too big but is the right size, only push the button once) without wasting my time by giving me information that I either already knew or could easily guess (I can get water from the sink, I need to use a cup). Can we use this concept in software documentation? What parts can safely be left out so that we are only highlighting the pieces that are really needed?

Miller, Lynn. Designing the User Experience at Autodesk (2009). Articles>Documentation>Technical Writing

Collaborative Walkthrough Video

Collaborative walkthroughs are a technique that my team used while rewriting our Help and adopting DITA. We believe that we were able to improve the user experience by improving the collaborative experience.

Bennett, Miranda. On Writing (2008). Articles>Documentation>Collaboration>Technical Writing

Converting to Information Mapping: A Case Study  

Cisco Systems, Inc., uses electronic media as the primary delivery means for customer documentation and training. Information Mapping® techniques are being developed as a methodology for creating and linking modules of customer information. After selecting the Information Mapping methodology, we found it necessary to customize it for our needs. To implement Information Mapping methodology, we defined a system architecture consisting of three main subsystems: a document management subsystem, an authoring environment, and a publishing or delivery subsystem, In parallel with the customization and development of a system architecture, several writers began to implement the Information Mapping techniques to provide content to be put into the system being developed.

Garrett, Aviva, Haggai Mark and Jan Johnston-Tyler. STC Proceedings (1996). Articles>Documentation>Writing>Technical Writing

Creating Professional Documentation with Linux Tools

While Linux lacks standard Windows tools such as FrameMaker, RoboHelp, and WebWorks Publisher, it's still a viable environment for technical writers. Linux users can take advantage of a number of documentation tools, including both free or open source software (FOSS) and proprietary software. All of them give technical writers the ability to author and publish professional documentation.

Nesbitt, Scott. Linux.com (2006). Articles>Documentation>Technical Writing>Linux

Creating Snippets from Multiple Blocks in Flare

When you are writing content in Flare, you may decide that you want to re-use some content that you previously added to another topic. We’ve discussed before how the best way to do this is to use a snippet, which essentially is a really long, formatted variable. To do this in Flare, you create a new snippet, then you locate the text you want to re-use, and copy the text out of that topic and paste it into the snippet. Then you replace the text in the original topic with the snippet, then insert the snippet into the new location.

Pehrson, Paul. DocGuy Training (2009). Articles>Documentation>Technical Writing>Madcap Flare

Creating Topics: Where do you Draw the Line?

It's hard to look at a page of text and try to decide where to divide things to create individual topics. That "bottom up" approach is kind of pointless, in fact. There are better ways.

Armstrong, Eric. Sun Microsystems (2008). Articles>Documentation>Information Design>Technical Writing