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.
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".
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?
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.
It may surprise you to find that the wikipedia entry for RTFM is a actually longer than the Wikipedia entry for technical communication. The RTFM response captures the disconnect between technical writers and end-users. Presumably, technical writers include the information in the help material that users ask about. Yet users often don’t take the time to consult the manual to find the answer. If only the users weren’t so lazy, the writer thinks, and mumbles RTFM in response to their question. On the flip side, the user thinks, if only the manual/application weren’t so crappy, then I wouldn’t need to ask others for the information I need.
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.
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.
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.
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?
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.
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.
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.
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.
Sure. We’ve been reducing word count in procedures for some time. It’s time to do more, however. As noted in an earlier post, we have to think mobile. Think small screens and small devices. Screen real estate will be at a premium.
A vast majority of documents (I consider print and online as documentation) often works to define the optimized error-free method of performing a task and provides a user with a straightforward solution. However, the user expects documentation to help solve problems and address errors. Thus, attention must be paid to potential problems users can have and how to correct them. Errors have different causes; the information designer should understand the potential types of errors since properly addressing each type requires a different approach in the design and documentation.
When you think of the crowd, you probably think about a specific mass of people who use the software and hardware that we document every day. The interesting thing about the crowd is that it doesn’t necessarily mean people outside of the enterprise in which you’re working. There are people in your enterprise who can do a lot to help you with the documentation, too. Developer, product managers, QA analysts. They all have knowledge that you can and should tap.
Some of my projects include community-involved documentation. When you work for a church, it’s not hard to find dedicated members willing and committed to sacrificing a few hours for a higher cause. To harness community efforts, I gathered up a large pool of volunteer names and formed a listserv. I communicated project needs with the listserv members and asked for help. Despite some contributions, the majority of volunteers are hindered by too many obstacles — access to information, time, standards, and more — to contribute much. As such, I’ve begun to change my expectations from content creation to content review and feedback.
In the world of development, the need to track bug reports and enhancement requests are a given. But they're not generally required for documentation, in the way they are for code Quite the reverse. For documentation, bug reports and enhancement requests provide little benefit, and generally impede progress. This post compares documentation and code, showing why bug reports and enhancement requests are so vital to the code base, and at the same time why those reasons simply do not apply to documentation.
Documentation for consumer products gets a bad rap. Often, it's deserved. But you can't paint all documentation with the same brush. This post looks at the good and the bad in consumer documentation, and at the elements which can make that documentation good.