http://tc.eserver.org/dir/Documentation A listing of the most recently indexed works about Documentation in the field of technical communication. en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif http://tc.eserver.org/dir/Documentation http://tc.eserver.org/35707.html http://tc.eserver.org/35707.html Listen up open source developers, if you want your project to succeed you’re going to have to do more than write great code; you’re going to have to document it, teach new users how it works and provide real-world examples of what you can do with it. That’s the message from Jacob Kaplan-Moss, one of the creators of Django, a very successful open source, Python-based web framework. At least some Django’s success can be attributed to its thorough documentation which is not just reference materials, but also includes tutorials, topical guides and even snippets of design philosophy. http://tc.eserver.org/35708.html http://tc.eserver.org/35708.html Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation. http://tc.eserver.org/35709.html http://tc.eserver.org/35709.html Now that I’ve discussed what kinds of technical documentation to write, I can move on to the question of how to actually develop a writing style that produces great technical documentation. So how do you learn to write (anything) well? There’s only one answer: you’ll learn to write well if you write. A lot. http://tc.eserver.org/35710.html http://tc.eserver.org/35710.html All good writers have a dirty little secret: they’re not really that good at writing. Their editors just make it seem that way. It doesn’t matter how well you’ve mastered the language; nobody, even grammar geeks, gets this stuff right on the first pass. If you really want to produce great documentation, it needs to be edited. http://tc.eserver.org/35714.html http://tc.eserver.org/35714.html The point of a quick-start guide is, as the name says, to help the users get on their feet as fast as possible. This requires the writer to ask, “What is the absolute minimum that someone needs in order to get started?” The next best question is “What is the user going to do the most often?” http://tc.eserver.org/35627.html http://tc.eserver.org/35627.html Seth Godin believes that everything reflects what you stand for—right down to your technical documents. Ever looked at Apple’s tech docs? http://tc.eserver.org/35634.html http://tc.eserver.org/35634.html The procedure I wrote about creating a Twitter list uses abbreviated content. This post describes the reasoning behind and decisions made in writing the topic. http://tc.eserver.org/35642.html http://tc.eserver.org/35642.html If you've installed older software in Windows 7, you might notice that .hlp-formatted Help files aren't recognized or supported. Microsoft offers a free download to read and manage those WinHelp files. http://tc.eserver.org/35666.html http://tc.eserver.org/35666.html In the past few years, there has been a growing interest in using automated translation in a business environment. In the past, automated translation was mostly implemented in government and defense areas, but nowadays there’s also a great interest from corporations that see the value automated translation can contribute to their organization. Let’s take a look at the different uses of automated translation, how it adds value to technical publications and how your teams can prepare content for automated translation. http://tc.eserver.org/35677.html http://tc.eserver.org/35677.html The shift in information development from a narrative to a modular writing style reflects the established shift towards modularization of source code. What can information developers learn from software developers? What are the challenges and benefits of the modular approach? http://tc.eserver.org/35679.html http://tc.eserver.org/35679.html How can you guarantee a clearly understandable user manual? Is it even possible to measure the quality of technical documents or does comprehensibility merely depend on the reader? To answer these questions for the Porsche AG, content analysis provider semiotis³ developed a model to help measure the quality of documents. http://tc.eserver.org/35684.html http://tc.eserver.org/35684.html Under the European law, the user manual is an integral part of the product. Faulty instructions or lacking safety information may lead to unforeseen liability claims. Several standards and directives give guidance on how to fulfill safety requirements, but also regulate design, use of language and information architecture of any high-quality manual. http://tc.eserver.org/35611.html http://tc.eserver.org/35611.html When it comes to video tutorials, long narrations quickly tire the audience. Why is that? The same reason my kids prefer the beach over Disneyworld: most videos are not user-led. http://tc.eserver.org/35612.html http://tc.eserver.org/35612.html Screencasting has a problem–it hasn’t evolved all that much over the 10 years or so since its inception. We still record the computer screen from a stationary position (dead centered) and we still present this flat, banal presentation to users sitting at their computers, which in and of itself presents problems (you’re looking at a computer screen on a computer screen–where does one end and the other begin). http://tc.eserver.org/35613.html http://tc.eserver.org/35613.html If you watch screencasts, you probably have seen some that are just worthless. How long did you stay to watch? Not long, I am sure. Why am I being so critical? Because it is true. http://tc.eserver.org/35614.html http://tc.eserver.org/35614.html For about Five years I worked for AT&T as a full time Instructional Designer and my worked involved the creation of training videos for the employees at AT&T. I loved it. It was creative, challenging and not stressful at all. http://tc.eserver.org/35616.html http://tc.eserver.org/35616.html If you want to get better at documenting your own code then this is the post for you. I have 5 simple tips to follow while coding to make the process easier. http://tc.eserver.org/35617.html http://tc.eserver.org/35617.html 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. http://tc.eserver.org/35605.html http://tc.eserver.org/35605.html 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? http://tc.eserver.org/35571.html http://tc.eserver.org/35571.html Here are a few tips for adding screenshots to your help topics. http://tc.eserver.org/35588.html http://tc.eserver.org/35588.html With in excess of ten years front line authoring experience and many more producing training documentation, I have a passion for language, its use and its odities. I was an Account Manager for a computer bureau providing a service to the advertising industry prior to taking the plunge into technical authoring. A large part of this was the production of technical training material for the ad-hoc customer training and classroom led courses held in the company’s training suite. http://tc.eserver.org/35535.html http://tc.eserver.org/35535.html Is less always more? I’m not sure. But if Apple’s minimalistic designs are any indicator of trends, minimalism in documentation is something to pay attention to. Here are five ideas for minimizing documentation. http://tc.eserver.org/35546.html http://tc.eserver.org/35546.html Many organizations produce in-house tools or modify commercially-available tools for their own use. These tools should get documented so they are of use to others in the organization. If this documentation is not created or is poorly written, it costs you twice. http://tc.eserver.org/35532.html http://tc.eserver.org/35532.html I saw this question posed in a discussion on LinkedIn, and thought that it deserved an answer from an IT Process Automation (ITPA) perspective. One respondent to the question stated it well: "The answer is simple, if there is not a common bond and governance mechanism between process documentation and the technology that is executing the process, the documentation eventually atrophies and collects dust." In my days as an independent ITIL consultant, I found that training and getting personnel to use process as part of their daily routine was at least as difficult as maintaining and updating process documentation. There is a chasm between theory and practice when it comes to process execution. http://tc.eserver.org/35520.html http://tc.eserver.org/35520.html Mohr details a method by which you can single-source content from an online help system to produce a manual for the same software application. http://tc.eserver.org/35523.html http://tc.eserver.org/35523.html In this first column on media matters, Lee discusses screen captures, including quality, manipulation, file type, file size, and more. http://tc.eserver.org/35525.html http://tc.eserver.org/35525.html I’ve been collecting examples of wildly inconsistent writing lately. I’m not sure why these have stuck out to me, but when I think of book sprints and community writing events, consistency is an important, though sometimes difficult, goal and outcome. http://tc.eserver.org/35528.html http://tc.eserver.org/35528.html In a case like this, you don’t need documentation made up of perfectly-chosen words and phrases. Instead, you need something that can be easily scanned, easily understood, and easily digested. Documentation that distills the main points quickly. Far more quickly than even the kind of minimalist documentation that I encourage can. http://tc.eserver.org/35530.html http://tc.eserver.org/35530.html This video on simplifying business, using the metaphor of organising a children’s party, made me smile and consider how successful documentation projects are managed. The presenter is suggesting managers need to, in complex systems, give up rigid control from above. Instead, they should watch for organisational patterns, encouraging the good and discouraging the bad. http://tc.eserver.org/35491.html http://tc.eserver.org/35491.html Documentation is important, from the end users to the developers, if you want your project to self sustain, if you want to ease the life of other people, and if you want your project to live a long and prosperous life. People were not in your head (and are not in your head) when you wrote that strange thing. 1-2 years from now you could be working for another company, what would be of other people who are trying to understand what you wrote? How would people easily understand how things work in a complex environment? http://tc.eserver.org/35495.html http://tc.eserver.org/35495.html As I've continued to teach my online RoboHelp class to students who attend from all over the world, one recurring issue has been confusion over the following three RoboHelp features: the start page, the project title and the default topic. The three files/names are totally different, having nothing to do with each other, but are commonly confused. By the time you are finished reading this text, I'm hoping that the confusion is a thing of the past. http://tc.eserver.org/35471.html http://tc.eserver.org/35471.html Doc whisperers are more commonly known as "senior technical writers", but what's in a name anyway? So if you want to be a great tech writer—start whispering. http://tc.eserver.org/35452.html http://tc.eserver.org/35452.html 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. http://tc.eserver.org/35468.html http://tc.eserver.org/35468.html Are we giving users the help they need, in the way they need it? Go minimal. http://tc.eserver.org/35438.html http://tc.eserver.org/35438.html Recently I’ve been working on a simple calendar project that uses a wiki for documentation. Although I’ve heard a lot about using wikis for documentation, and have even used them in the past, I ran into a few surprises this time. http://tc.eserver.org/35414.html http://tc.eserver.org/35414.html An engineer at a company once called me and asked me how much it would cost to edit a Service Manual that he had written for a medical device. I asked him to send it to me so that I could give him a quote. When I received it I saw to my amazement and horror that he had written a 200 page manual (including many graphics) in Excel. When I asked him why he didn't use Word, he replied 'I'm an engineer I know how to use Excel, not Word.' http://tc.eserver.org/35419.html http://tc.eserver.org/35419.html I honestly can't remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that's a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase. So why do we still maintain a traditional view of how information should be provided? http://tc.eserver.org/35421.html http://tc.eserver.org/35421.html It's a simple fact of life. Developing products in today's world requires shorter cycles, sensitivity to customer needs, and a focus on deliverables that breaks the old waterfall development paradigm. More and more there is a need for teams to focus on the entire development process and deliver precisely what customers need with little or no fluff. As products move towards the user-centric model of product development the push is for more intuitive interfaces with little need for documentation -- or does it really? http://tc.eserver.org/35423.html http://tc.eserver.org/35423.html 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. http://tc.eserver.org/35434.html http://tc.eserver.org/35434.html A product is only as good as its information. With good information, customers can use the product--be it a piece of software, a hand-held electronic device, or a supersonic aircraft--and are more likely to hold a good opinion of its manufacturer. Without good information, no matter how good the product is, customers will be frustrated and will probably look elsewhere. It's not a stretch to say that the documentation project manager is instrumental in determining whether a product succeeds. http://tc.eserver.org/35435.html http://tc.eserver.org/35435.html What does structured authoring mean to you? Structured authoring is a publishing workflow that lets you define and enforce consistent organization of information in documents, whether printed or online. What it means to me: defining a goal and assembling architected topics to help the reader achieve that goal. http://tc.eserver.org/35436.html http://tc.eserver.org/35436.html This a short video overview of managing a documentation project. It's something we put together as a test of some of the functionality of Techsmith's Camtasia software. http://tc.eserver.org/35403.html http://tc.eserver.org/35403.html A wiki can be a Frequently Asked Questions repository, much like the knowledge bases in their heyday in the late 80s. My favorite line from the blog entry has to be its closer: 'It's about a different way of thinking around how to interact with the community.' And that is what I have explored with my wiki presentation, about how to build community with a wiki and be an active member of that community. But what are other uses of the wiki? http://tc.eserver.org/35407.html http://tc.eserver.org/35407.html While I'm a firm believer in the primacy of content over appearance, aesthetics are definitely a part of drawing people into documentation and engaging them. There's nothing wrong with making online assistance or a printed manual attractive. It doesn't need to be a beautifully-designed work of art, but it should be something a little more than blocks of black text on a white page. http://tc.eserver.org/35378.html http://tc.eserver.org/35378.html Power user. It’s a term that I don’t like. But there definitely are people out there who are working with the software and hardware that we document who want more than just basic information. Getting them that information can be tricky. http://tc.eserver.org/35356.html http://tc.eserver.org/35356.html Provides a historic overview of research on printed software tutorials. Describes developments in design approaches, refinements in design, and user experience. http://tc.eserver.org/35339.html http://tc.eserver.org/35339.html Help authoring tools (HATs) are specialized editors and converters to create online technical documentation. Today, many help authoring tools also provide features for single source publishing, which means that you can generate several output formats and versions from one shared text source. While most tools manage to produce different online formats like browser-based help and compiled help very well, only few tools can also produce printed user manuals (or PDF) of professional quality. Big differences also exist between the tools when it comes to translating your projects into foreign languages. http://tc.eserver.org/35340.html http://tc.eserver.org/35340.html Checklist of key criteria for selecting a tool to take screen captures (screenshots / screen dumps). Screen captures are used within all forms of software documentation, such as user manuals, online help files, interactive demos and tutorials, but also for web sites and brochures. http://tc.eserver.org/35341.html http://tc.eserver.org/35341.html Checklist of key criteria for selecting a tool to create interactive software demos (so-called screencasts). Software demos are not only used on web sites but increasingly also as standalone tutorials or embedded within online help files and other sorts of software documentation. http://tc.eserver.org/35348.html http://tc.eserver.org/35348.html Marktüberblick über empfehlenswerte Tools zum Erstellen von Software-Demos (engl. Screencasts). Software-Demos werden nicht nur für Marketing-Zwecke auf Webseiten verwendet, sondern häufig auch als Ergänzung zur Technischen Dokumentation von Software: z.B. als eigenständiges Tutorial oder auch als integrativer Bestandteil einer Online-Hilfe oder sonstiger Software-Dokumentation. http://tc.eserver.org/35322.html http://tc.eserver.org/35322.html What Are These Tools? Screen recorders that let you: record a series of screens as frames in a movie – like chaining together screen shots; annotate the frames with text captions, high-lights, and other effects for enhanced learning and explanation; add testing – informally through “dead-end” quizzes or formally using eLearning; publish the result. http://tc.eserver.org/35334.html http://tc.eserver.org/35334.html In the US today, there are 82.5 Million Content Creators 13.9% create content in virtual worlds 18.1% create video content 23.9% create blog content 79.7% create content on a social network. All we need is a standard that will support the topic- based nature of “how to” video content XML, and by extension, DITA, seemed to be a perfect fit. http://tc.eserver.org/35338.html http://tc.eserver.org/35338.html Web 2.0 includes: wikis, podcasts, blogs, widgets/gadgets, social networks … and combinations of all the above. Not everyone contributes equally – Creators (18%), Critics (25%), Spectators (48%). But all are important. http://tc.eserver.org/35304.html http://tc.eserver.org/35304.html This document summarizes the differences in use between OpenOffice.org Writer 1.1.x and Microsoft Word (various versions). http://tc.eserver.org/35300.html http://tc.eserver.org/35300.html There’s a place for a lighter touch in much of the online documentation we write. It’s a delicate balance. On the one hand, it’s important that the writing style does not annoy or offend the reader and does not detract from the content. We also need to be aware of people whose first language is not the one we’re writing in. On the other hand, the occasional touch of humour or personality can focus the reader’s attention onto the page. http://tc.eserver.org/35301.html http://tc.eserver.org/35301.html I have no idea what our users want. I do know they want information, and I know they want that information to be kept up to date as our product evolves and as far as those basic needs are concerned, I’m happy that we are meeting them. Beyond that I admit I’m not really that sure. http://tc.eserver.org/35303.html http://tc.eserver.org/35303.html Just as I would with words, I'll cut out the obvious and whatever does not add value. I prefer an additive approach (put it in only when the words seem inadequate) over a subtractive approach (take it out if it seems superfluous). In other words, I'll be more open to screen shots in the future, but they have to work themselves into the document, not just be their by entitlement until expelled. http://tc.eserver.org/35292.html http://tc.eserver.org/35292.html How can we reduce the amount of time needed for employees to read instructions, so they can easily follow procedures? Is there a way to layout the procedure and the supplementary information so it is not intertwined? http://tc.eserver.org/35285.html http://tc.eserver.org/35285.html 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. http://tc.eserver.org/35288.html http://tc.eserver.org/35288.html What issues and legalities do we as Technical Communicators or Wiki Administrators need to be aware of as we move towards collaborative authoring projects and so forth, especially when documenting open source software? http://tc.eserver.org/35290.html http://tc.eserver.org/35290.html Those within technical communications have long argued that product documentation provides significant value in terms of a customer satisfaction and downstream savings in customer support and service. In the broader, enterprise perspective, however, documentation is generally viewed as simply one of many requirements for product launch. This perspective is often the result of the lack of visibility that is generally available into the business value contributed by product documentation. Aberdeen investigated and isolated the quantifiable business impact of technical communications makes for 165 participating companies. An analysis of this data indicates that when leveraged effectively, technical communications stands to contribute as much as a 42% increase in customer satisfaction and an associated 45% increase in product revenue. This report provides a quantified framework for understanding the potential impact on technical communications makes for business profitability as well as the best practices to adopt to drive greater value from this organization. http://tc.eserver.org/35281.html http://tc.eserver.org/35281.html These points are not meant to be all-inclusive. However, if you are new to tech writing, this should put you on the right road. http://tc.eserver.org/35268.html http://tc.eserver.org/35268.html As simple as the concept of backing up your work might be, I am constantly surprised when I hear from even veteran Captivate developers that a project has become corrupt (the project, which was fine yesterday, won't open today). The fix? If the project won't open, there's a good chance that the only thing anyone can do is copy a backup project to the local disk and then open the backup. Oh, you don't have a backup? Ouch! http://tc.eserver.org/35265.html http://tc.eserver.org/35265.html I recently switched from RoboHelp 7 to Flare 5. I’m not the person to ask about the merits of one over the other because I don’t have enough experience with Flare yet. Because I’m coming to version 5 with my knowledge being only that which my colleagues have told or shown me, I hope to make life easier for anyone moving from RH to Flare or at least trying Flare out. http://tc.eserver.org/35225.html http://tc.eserver.org/35225.html Perhaps the true measure of a good idea is its persistence, even though folks are slow to pick up on it. SGML is a good example. It seemed like a great idea, but for a long time, had trouble getting traction in the general tool space. Then it started showing up at technical communication conferences wearing a name badge that said, “Hi, my name is DITA,” and suddenly, it’s a hit! http://tc.eserver.org/35207.html http://tc.eserver.org/35207.html Are the days of print documentation over? How ‘usable’ is your print documentation? http://tc.eserver.org/35210.html http://tc.eserver.org/35210.html As help systems continue to evolve, whatever name they are called, we will increasingly have to face responsibility for their content, and bring their expertise to what we write. The new systems provide us with all the required tools that tell us the problems with their content. It is up to us to leverage that information to provide better content, and act as ambassadors for products that we write. If writers can go a step ahead, and use their help information to sell products, and reduce the burden on customer support, we would have truly arrived. http://tc.eserver.org/35212.html http://tc.eserver.org/35212.html Why do product manuals sound formal and stiff-upper-lipped? Why don’t users read manuals? These questions have haunted the precincts of Technical Writing for quite some time now. From what I have seen in Indian writers, I am forced to conclude that English Composition, as we were taught in school, is the culprit. Our merit was based on how verbose we were. They judged our style based on how ‘formal’ we were. Take for example, the leave letter. I am sure you have written a few in school or college. Rewind and replay one of those leave letters. Right from the salutation (Respected Sir/Madam) to the signature (Faithfully/Obediently yours) it reeks of colonialism. And, we have yet to learn our lessons. In this age of globalization (or globalisation, to my stiff-upper-lip comrades), it is important to pay attention to the three Cs: Consistency, Context, and Culture. http://tc.eserver.org/35189.html http://tc.eserver.org/35189.html This Fast Track tutorial demonstrates how to create automatic line numbering in a code block. http://tc.eserver.org/35190.html http://tc.eserver.org/35190.html This Fast Track tutorial demonstrates two methods to call Context-Sensitive Help in a Web Form. We'll discover how Unobtrusive DOM/JavaScript achieves the desired result in calling Context-Sensitive help, and demonstrate how to keep the Structure, Presentation, and Behavior layers of a web page completely separate from one another ensuring good practice with current web standards and accessibility rules. http://tc.eserver.org/35192.html http://tc.eserver.org/35192.html The idea of a Book Sprint is that you can get lots of documentation written in a focused amount of time with the right team and some amount of content already in place. Gathering people in the same room when possible is extremely helpful and motivating as well. http://tc.eserver.org/35195.html http://tc.eserver.org/35195.html For simple, commonly known actions in a closed environment, you probably can design your way to a “no user documentation” approach. Good design can also lead to less documentation. However, customers may expect to do more than that with a product and, in those situations, documentation can play a key role in meeting those expectations. http://tc.eserver.org/35203.html http://tc.eserver.org/35203.html One of the tips for creating a help project is to keeps things simple. This applies as much to the content as it does to the manner in which it is produced. The tool used to produce it has a big bearing on how simple the documentation process is of course but sometimes you just have to bend the rules. http://tc.eserver.org/35204.html http://tc.eserver.org/35204.html A picture is worth a thousand words. If that’s true, then a video should be worth several pages of those words. Video is the ultimate in showing and telling. Instead of relying on lengthy procedures, a short, well-made video can walk a user through what needs to be done to complete a task. But is video the be all, end all? Is it really the next stage in the evolution of documentation? Will it supplant text and static images? http://tc.eserver.org/35179.html http://tc.eserver.org/35179.html User interface (UI) patterns have the potential to make software development more efficient. The prospect of such efficiency gains has led to interest in user interface (UI) patterns by individuals and organizations looking for ways to increase quality while at the same time reducing the costs associated with software development. http://tc.eserver.org/35154.html http://tc.eserver.org/35154.html As wikis mature, we’re using them for more complex business cases such as technical documentation, business analysis and project management. It’s becoming more and more interesting, if not essential, for wikis to support the import and export of content to and from other formats. Most wikis allow you to convert their pages at least to PDF and HTML. But what of other formats, and what about tools for getting content into wikis as well as out of them? http://tc.eserver.org/35158.html http://tc.eserver.org/35158.html When it comes to an about page, think outside the box. Try to think of something new and creative that’s different form the rest of your site. Of course display images of you / your staff, and descriptions of each, but try to lay it out in a very fun way, whistle keeping it clean and readable. http://tc.eserver.org/35125.html http://tc.eserver.org/35125.html I’m advocating boiling the documentation down to the essentials. Remove any superfluous material. Tell the user how to do things with a piece of software or a gadget, not what that something can do. You might wind up with documentation that’s just a set of procedures connected together by linking material and cross references. Don’t bog them down with what’s not necessary for them to get things done in a fast and efficient way. http://tc.eserver.org/35126.html http://tc.eserver.org/35126.html This Authors’ Guide tells you everything you need to know to write Missing Manual. It starts out by giving you a brief introduction to the Missing Manual way of explaining things and then takes you through the nitty gritty of style guidelines, figure formatting, and so on. http://tc.eserver.org/35116.html http://tc.eserver.org/35116.html Technical writers love the written word. Perhaps, we love it a little too much? We need to ask ourselves is the written word the best thing for documentation? Is it the best thing for us as an industry, and is it the best thing for you as a content developer. http://tc.eserver.org/35108.html http://tc.eserver.org/35108.html The notes for a presentation (titled Thinking Outside the Book: Wikis for Writing and Delivering Documentation, that discusses the whys, the tools, and the techniques of using wikis for documentation. http://tc.eserver.org/35082.html http://tc.eserver.org/35082.html Usability is the combination of effectiveness, efficiency, and satisfaction with which the users accomplish defined goals in a given environment. User-centered documentation matches the users' mental model, thereby helping the users find information they want quickly and easily in their hour of need. The list of documentation usability criteria is fairly subjective at this time, and various opinionated discussion groups have contributed to this. Usable documentation is based on a deep understanding of the users' tasks, and this understanding can only be gained through interviewing representative users. Applying information architecture techniques, the content within documentation should be properly chunked so that the users can assimilate the information properly. Procedural guides should have a well-defined and searchable index that enables users to connect key application terms to their correct context. User-friendly documentation is always succinct, but never at the expense of omitting critical/useful information. It should be developed using a structured process so that it starts with the big picture and gradually adds lower level of details, addressing the needs of every unique group of users. Finally, the documentation must be tested among a representative group of users, and their feedback should be incorporated to make sure that it has met all of the major usability criteria. http://tc.eserver.org/35083.html http://tc.eserver.org/35083.html Technical communication is changing rapidly. If you’re not ready for that change, it’s going to really catch you off guard. Anne Gentle's book Conversation and Community is an excellent guide to rolling with those changes, and for staying ahead of them. This article takes a close look at the book. http://tc.eserver.org/35080.html http://tc.eserver.org/35080.html Project teams may recognize that reviews are not working well, though the may not understand why. A valuable solution is to conduct ”lessons learned” analysis following the end of the project. Too often, though, post-writing-project analysis receives little commitment or meaningful effort, but why? http://tc.eserver.org/35039.html http://tc.eserver.org/35039.html A small documentation team working on a tight budget can now use the tool ecosystem enabled by the DITA standard to create the sophisticated content that previously required long and expensive projects. The author spent just nine person-weeks over three years to replace a custom XML system with a DITA system based on a combination of off-the-shelf software, authoring conventions, and custom scripts. http://tc.eserver.org/35040.html http://tc.eserver.org/35040.html uScrum (uncertainty Scrum) is an agile process developed by a small team at Altitude Software to manage the process of writing user documentation. uScrum manages uncertainty and the unknown, allowing writers to quickly react to changing conditions. uScrum uses orders of ignorance to understand the difficulty of tasks, allowing the team to effectively prioritize regular work together with difficult creative work. http://tc.eserver.org/35041.html http://tc.eserver.org/35041.html With DITA implementations on the rise, and an entrenched DocBook community already in place, the resulting market interest has spurred interest in automated DocBook to DITA conversion. So I would expect offerings of automated DocBook to DITA conversion scripts to emerge in the next 6-10 months. This article addresses the real questions, "What should I expect from automated tools?" and "Will they work for me?" from the viewpoint of live experience with numerous DocBook to DITA conversions. The answers to these questions are not usually obvious. http://tc.eserver.org/35043.html http://tc.eserver.org/35043.html This top ten list is based on interviews conducted by TheContentWrangler.com with technical writers at more than 20 software companies—tech writers that are actually using DITA to create documentation today. http://tc.eserver.org/35047.html http://tc.eserver.org/35047.html 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. http://tc.eserver.org/35027.html http://tc.eserver.org/35027.html 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. http://tc.eserver.org/35025.html http://tc.eserver.org/35025.html 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. http://tc.eserver.org/35015.html http://tc.eserver.org/35015.html 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. http://tc.eserver.org/35017.html http://tc.eserver.org/35017.html XML provides a way to identify data items and subcomponents within any structured data set, but has its roots in documentation development and production. Robust, open standards for XML document markup and a rich set of freely available tools for XML document parsing and format conversion make it easy to install and configure a complete documentation development and formatting environment on any UNIX® or Linux® system. http://tc.eserver.org/35018.html http://tc.eserver.org/35018.html Discover simple solutions to reuse information in XML documentation, such as how to use XInclude to include other documents at a given point in a document and how to use XPointer to include small document fragments from other documents or a similar pool of information in XML format. Also, get tips for structuring XML documentation to simplify information reuse, and learn how to maintain stand-alone documents that you can incorporate into larger documents. http://tc.eserver.org/35019.html http://tc.eserver.org/35019.html XML is an optimal format for writing documentation that you can use with many different documentation software packages and production environments. In this third article in the series, discover how to create single-source documents that can produce output in a variety of different output formats. http://tc.eserver.org/34929.html http://tc.eserver.org/34929.html Localization includes translating, explaining, and adapting a document for use in a specific culture. This article presents the case of a form for reporting the findings and decisions of pre-production meetings held during development of electronic products. The need to localize such a document may seem less obvious or critical than the need for sales documents like manuals, but this case demonstrates the same cultural requirements and, furthermore, the requirements of corporate differences. To meet local needs, the comprehensive preparation that localization requires should follow specific methods in each step of a process corresponding to the general writing process, like the stages defined in common technical writing texts. The deliberate use of an effective writing process to localize documents will improve results. http://tc.eserver.org/34899.html http://tc.eserver.org/34899.html People use different terms to describe quality and if they actually use the same term, then it is highly unlikely that they will use the same definition for the term. So the first problem faced in the review process is the vocabulary used to describe quality attributes in a document. http://tc.eserver.org/34909.html http://tc.eserver.org/34909.html Document reviews should be used as a tool to build quality into research and technical reports. In most handbooks for professional writers, review is recommended for clear and simple reasons: it is intended to identify problems and suggest improvements that enable an organization to produce documents that accomplish its goals and meet readers’ needs. http://tc.eserver.org/34910.html http://tc.eserver.org/34910.html I have a theory about why we continually see subject matter expertise for review applied to the task of copy-editing, and why that practice is so hard to change. The theory is built around how we: learn to write, learn to review, and ask for review. http://tc.eserver.org/34880.html http://tc.eserver.org/34880.html This article investigates the contribution visual rhetoric and rhetorical genre studies (RGS) can make to health care education and communication genres. Through a visual rhetorical analysis of a patient record used in an optometry teaching clinic, this article illustrates that a genre's visual representations provide significant insights into the social action of that genre. These insights are deepened by an insider analysis of the patient record that highlights how content analyses of visual designs need to be elaborated by contextual considerations. A combined visual rhetoric and RGS analysis shows that clinical novices learn to interpret the record's visual cues to safely traverse the complex requirements of this apprenticeship genre. The article demonstrates that visual rhetoric research can meaningfully contribute to the understanding of genres by presenting an enriched contextual analysis achieved by consulting with context insiders. http://tc.eserver.org/34885.html http://tc.eserver.org/34885.html The author argues that users see texts as tools when they recognize the texts' specific value and function within highly localized use settings. The author argues that users "ground" their texts to local use settings by altering the ways in which the texts structure and represent information (e.g., underlining, annotation, and sketching). The author discusses three practices by which texts are grounded as tools in document reviews: mode shifting, layering, and marking. These practices reflect different ways by which users add, subtract, and restructure information in a text so that it is usable under very specific conditions. This article explores document review as a practice in which grounding is the object of discussion (how others use the reviewed documents) and a practice by which review is facilitated. These observations will be important for exploration of technology to support "grounding" practices. http://tc.eserver.org/34889.html http://tc.eserver.org/34889.html Lately I’ve been creating context-sensitive help for an online application. As part of my strategy, I’ve been trying to follow Theresa Putkey’s advice in “Usability in Context-Sensitive Help.” In her article, Theresa recommends providing more than just the steps for a specific task in the context-sensitive help window. Instead, she says to show more contextual links, including answers to why, when, and who questions, because too frequently the user who searches for help may have needs outside the specific task you describe. http://tc.eserver.org/34861.html http://tc.eserver.org/34861.html In open source, the standards for documentation are typically quite low. But they don't have to be. http://tc.eserver.org/34863.html http://tc.eserver.org/34863.html Capturing the essence of a topic is the heart and soul of good writing and editing. If you cannot tell what the main idea is, you cannot write it either. And if you cannot write it, how would you expect your readers to get it? So it all starts with you. Thankfully, it is not mysterious process. Here are two techniques that you can use to weed out the irrelevant details from your core idea. http://tc.eserver.org/34806.html http://tc.eserver.org/34806.html In our consultancy, we have developed a set of terms that represent what we consider to be an effective set of descriptive markers. Markers that help to measure how well a document is communicating. We characterize our set of markers as “Document Standards” for all forms of technical and scientific writing. http://tc.eserver.org/34807.html http://tc.eserver.org/34807.html Most people involved with authoring and reviewing process do not have good markers to inform them of the overall communication quality of a document. So without good markers they are left to utilize really poor markers to help them measure document quality. http://tc.eserver.org/34809.html http://tc.eserver.org/34809.html If you're moving to Flare from another help authoring tool, you'll find that Flare's stylesheet editor is very powerful but different than other stylesheet editors that you may have used. And if Flare is your first help authoring tool, you may find the stylesheet editor overpowering at first. To help you get over that initial hump, Hyper/Word Services offers a stylesheet for Flare that will help you learn to use the stylesheet editor, and that may apply to actual projects. http://tc.eserver.org/34791.html http://tc.eserver.org/34791.html Defining quality means developing expectations or standards of quality. Standards can be developed for inputs, processes, or outcomes; they can be clinical or administrative. Unfortunately when it comes to documentation, many companies only focus on the standards related to time and accuracy. Quality standards should be in place for all aspect of the documentation development pathway—moving from planning, to authoring, to reviewing. http://tc.eserver.org/34804.html http://tc.eserver.org/34804.html 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. http://tc.eserver.org/34788.html http://tc.eserver.org/34788.html Writing more simply helps keep content more manageable and can increase its usability. So why do we continue to litter content with screen captures, which can be difficult to manage and often duplicate what users already see in application interfaces? http://tc.eserver.org/34778.html http://tc.eserver.org/34778.html A technical writer’s blog on Wordpress Linking to external blog posts from our documentation with 3 comments At work, we’ve just started a new set of documentation pages called “Tips of the Trade“. The project is still in the early stages. I thought other tech writers might be interested, so I’m blogging about it now. There will be a page for each of the products we document. The pages contain a set of links to useful blog posts written by people out there on the www. It’s a way of giving our readers more information and a way of involving external bloggers, developers and authors in our documentation. http://tc.eserver.org/34779.html http://tc.eserver.org/34779.html In early March we opened up the Atlassian documentation to the wider community. We added a CC-by (Creative Commons Attribution) license to our product documentation. We invited people to contribute to our documentation after signing an Atlassian Contributor License Agreement (ACLA). At that stage, the ACLA was just starting its three-month trial. The trial period has now ended, and we're delighted to say: it's a go! http://tc.eserver.org/34784.html http://tc.eserver.org/34784.html DocBook is a set of tools for implementing XML (Extended Markup Language)-based structured documentation. It is developed back in 1991 and is widely used today by those technical writers who generate single-sourced documentation. It is especially well suited for software, hardware and networking documentation. http://tc.eserver.org/34777.html http://tc.eserver.org/34777.html In order to understand the way marketing people see the world, it’s worth reading Blogs on marketing (by people such as Seth Godin), the Cluetrain Manifesto, and reading a few books on marketing. http://tc.eserver.org/34769.html http://tc.eserver.org/34769.html This PDF is not a guide to any specific language, and so would be great for developers who do not code in any specific language (or who code in more than one language). http://tc.eserver.org/34753.html http://tc.eserver.org/34753.html One technical communication team delivered answers to user questions in two clicks with a help file created in DITA XML, using structured writing, different tools and a new information architecture. Content was linked one-to-one with application elements. Hyperlinks in one area of each screen make user access easy. The communicators established a linking strategy, used natural language for guided navigation and developed a reuse strategy involving references instead of duplication of content. The result was delivery of an InfoCenter that's easy to maintain and to expand, which a portion of the team will be doing for the next 20+ years. http://tc.eserver.org/34710.html http://tc.eserver.org/34710.html 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. http://tc.eserver.org/34711.html http://tc.eserver.org/34711.html Part of the problem in our attempt to demonstrate value is that our help deliverables look the same as they did 15 years ago, more or less. Online help and a PDF manual. It’s not a format that engages users. The web marches forward with innovation after innovation, while the technical communicators are figuratively hunched over keyboards, staring at CRT monitors, wearing 1950s horn-rimmed glasses, typing away. http://tc.eserver.org/34712.html http://tc.eserver.org/34712.html Help needs to be a mile wide—it must cover everything—and 30 seconds deep—tackling only small amounts of detail at any given point. http://tc.eserver.org/34713.html http://tc.eserver.org/34713.html Technical writing is a cost activity, not a revenue or a profit activity. http://tc.eserver.org/34714.html http://tc.eserver.org/34714.html Embedded user assistance is only part of a complete documentation plan. It does not replace the need for other types of content. For example, embedded user assistance is not a good delivery mechanism for comprehensive concepts and detailed discussions of a topic with strategy and best practice guidelines. However, with a strong design, embedded user assistance can support the immediate needs of the user and provide a valuable, contextual link that steers the user into the other parts of the documentation as needed. http://tc.eserver.org/34717.html http://tc.eserver.org/34717.html More and more, I think it’s time to discard main approaches to tech writing and come up with new methodologies. The world and technology is changing so much that I think it’s time to start fresh. Just as sometimes when you’re working on a sentence and you tweak it and change it, but it’s still not quite right, and you finally just drop it and come up with something different. Perhaps it’s time to drop existing methodologies and develop something new instead of trying to tweak what’s there to fit what’s happening now. Perhaps the old methods no longer work. http://tc.eserver.org/34706.html http://tc.eserver.org/34706.html 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. http://tc.eserver.org/34704.html http://tc.eserver.org/34704.html 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. http://tc.eserver.org/34696.html http://tc.eserver.org/34696.html Beyond the obvious impact on the Social Web, Google Wave is also going to change aspects of every business that currently relies on communication and collaboration tools of any sort, including the ubiquitous but lowly email. http://tc.eserver.org/34681.html http://tc.eserver.org/34681.html Last week Google released Google Voice, a service that allows you to integrate all your phones into one number and includes a host of features, including voice mail, recording, conference calling, and other services. To help users get started, Google Voice has a list of 20 short videos. Only the overview video contains animation. It’s certainly the video they’ve put the most work into, and it also functions as marketing collateral. http://tc.eserver.org/34682.html http://tc.eserver.org/34682.html Writing user manuals isn't so difficult if you start with a clear understanding of the structure of such documents. This post will provide you with some guidelines for producing a great manual, and links to templates to help you get started. http://tc.eserver.org/34676.html http://tc.eserver.org/34676.html In this Web 2.0, connectedness-driven world, we acknowledge that to some extent, people seek out the most up-to-date information. If it was published in 2008, it’s ancient history. If it was published last month, it’s not as bad, but still not optimal. I think time stamps and version numbers are probably sufficient to suggest accuracy and “up-to-dateness.” What do you think?