Articles>Documentation>Software

Why Help Authoring Tools Will Fade

Using any of the standard authoring tools — Flare, RoboHelp, Author-It, Doc-to-Help — leaves you with the ridiculous model of a single author working from a single vantage point from a single organization trying to pull together an ocean of information. Because that model is untenable and unscalable, HATs will fade in favor of collaborative web-based authoring technologies.

Writing Great Documentation: What to Write

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.

To the Man With a Hammer Everything Looks Like a Nail

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.'

Choosing a Help Authoring Tool

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.

Choosing a Screen Capture Tool

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.

Choosing a Screencasting Tool

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.

Marktüberblick Screencasting Tools

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.

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.

Hey Rocky – Watch Me Pull a CMS Out of My HAT

When companies decide whether or not to adopt a CMS or continue using a HAT, there are many factors to consider. Perlin outlines elements of both CMSs and HATs that could help you determine which is best for your organization.

Using Master Pages in RoboHelp 8

Master Pages, a new concept introduced in Adobe RoboHelp 8, intends to provide flexibility in controlling the layout of topics, where in an author may separate the actual content from the layout of the output and may do it from a single place. In Adobe RoboHelp 8, a user may use Master Page as a Layout and Styling canvas where one may put basic HTML elements to be used for Layout purposes.

Guidelines for Good Sample Code

Sample code often provides the quickest, clearest way to learn how an SDK works. If you have software engineering experience, then you should already know many principles for writing good code. However, what you may not realize is that some of the good practices that you learned for writing good production code do not apply to writing good sample code. Some techniques, such as comments and clear variable names, apply to both production code and sample code. However, there are good reasons to use hard-coded values in sample code, which should be avoided in production code, and there are good reasons to avoid object-oriented designs when writing sample code.

Writing Technical Documentation with Sphinx, Paver, and Cog

I've been working on the Python Module of the Week series since March of 2007. During the course of the project, my article style and tool chain have both evolved. I now have a fairly smooth production process in place, so the mechanics of producing a new post don't get in the way of the actual research and writing. Most of the tools are open source, so I thought I would describe the process I go through and how the tools work together.

Flexibility and Adaptability

There’s a lot of tool fetishism in the documentation world. We all succumb to it in one way or another — I used to think it was FrameMaker or DocBook, or nothing. Ah, the folly of youth. But that attitude severely limits you as a professional. For a consultant or freelancer, it’s only a few steps away from suicide.

Ten RoboHelp Tips You Won't Want to Miss

I've been using RoboHelp for nearly a decade now. I started off with an older Word-based version to create WinHelp, and now I work with the HTML version to create WebHelp for locally installed and server-based products. Here are a few RoboHelp tips that I've found useful in my day-to-day help authoring responsibilities.

Eight Steps to Successful Software Documentation

Whether software documentation is designed for a company’s internal users or for a variety of end customers, one thing is for certain: Documentation that is well written, well structured, easily accessible, and thoroughly compliments the software it supports can play a significant role in a product’s overall success. And it doesn’t matter if the documentation stands alone or it is integrated with the product. As long as it is properly planned, developed, and configured, success is eminent.

Getting FLOSSy: Acrobat Killer Or HAT Replacement?

Some writers truly hate Adobe Acrobat and any tool that can do the job better is worth a shot, particularly if it’s open source and easily navigated. Flossmanuals.net introduces FLOSS which does a lot of the single desktop Acrobat Pro’s job - collaboratively and open source.

The First Line of Support

Customer support costs account for as much as 60 percent of a high-tech company’s total costs. Documentation is the first line of support for most customers, and customers usually use documentation to find the answer to a problem they’re having. The inevitable result of poor or nonexistent documentation is that more people try calling the customer support lines for help.

Language Quality-Assurance Software

Explores the benefits of using Language QA Software to optimize documentation for organizations and companies.

Why Software Applications Need Product Blogs, and Why They Don't Get Them

I'm convinced that even internal software, which never sees the light of WWW, still needs a blog as much or more than products sold online. Even so, numerous corporate restrictions, standards, and culture will present seemingly insurmountable barriers to blogs.

XML Documentation: The Missing Link (1)

Technical documentation is a prime beneficiary of XML technology, with standards such as DocBook and DITA. However, while XML revolutionized the way technical documentation is written, it did nothing to help documentation teams improve the collaboration process with the SMEs and other invested parties. In some cases, things got worse, with another layer of complexity added between the documentation team and the documentation stakeholders. Where is the missing link?

XML Documentation: The Missing Link (2)

Sharing XML documents during the writing and review process is a missing link in the XML publication chain. While Office or PDF applications help, they also add another extra-layer of complexity and lose the 'XML awareness' of our initial document. That's where LiveTechDocs comes into play.

XML Editors for Technical Documentation

Looking through my Programs folder, I see many programs I use to work with XML documentation. Which one is my favorite? Well, that depends on the size of my project, the size of my budget, and the file I am working on.

Der Weg zum absoluten PDF-Standard in der Technischen Dokumentation

Kein Wunder müssen Technischen Redakteure die ganze Zeit Druckdaten aufbereiten, wenn jede Druckerei ein anderes Datenformat verlangt. Eine Lösung musste her. Ein Standard. Und so ist auch PDF/X-3 ein Thema in der Technischen Dokumentation.

The Importance of Software Documentation Standards

The look and feel of a help system can differ greatly from one product to the next, as can the writing. So how can the technical writing community emphasize the importance of software documentation standards and create a more unified help experience that users can adapt to?

Editing Guidelines for Software Documentation

Software documentation can be difficult to review, so it helps to have some editing guidelines to keep you focused. Let's face it; software documentation isn't exactly exciting reading material. But you should be able to complete the job in a productive manner if you keep your coffee cup full and follow the editing guidelines below.

Twenty-Two Tips for Writing Software Documentation Users Will Actually Read

How do you go about writing technical manuals for software without going insane? Here are some guidelines you can follow to maintain your sanity when writing software documentation.

All About Madcap Flare

Madcap Flare is one of the most powerful online help authoring tools on the market today. In this podcast, Paul Pehrson, MVP in the Madcap Software forums, talks about Madcap Flare in depth.

Why Wise Users May Not Read Computer Documentation

Wise computer users may not read documentation because they do not have time to read all the material that is shipped with software products and because the useful lifetime of documentation is so short. This proposition is supported by statistics for a sample of manuals for typical commercial software.

Systems and Programming Documentation for Technical Writers with No Data Processing Background

This workshop teaches technical communicators what to include in internal documentation, how to interview and work with technical people, and basics of how to 'read' and evaluate code.

Preserve Changes in RoboHelp for a Linked FrameMaker Book

While it is ideal to maintain all the content in FrameMaker, there are special situations which may require the RoboHelp content to be out of sync from FrameMaker documents either for short duration or for small set of topics. These special situations can relate to project deadlines or project requirements which make the process of maintaining a single source difficult.

Accommodating Active Learners in Software Documentation Decisions

Recent research focusing on a minimalist approach to computer software documentation has explored ways to design computer software tutorials and workbooks for users with an active learning style. The principles of minimalism and active learning styles, however, are less frequently applied to traditional reference manuals. This paper reviews several elements of minimalism and suggests ways to apply strategies for active learners to traditional reference manuals.

Evaluating the Effect of Iconic Linkage on the Usability of Software User Guides

This study investigates whether Iconic Linkage--the use of the identical wording to present the same information recurring in a text--can improve the usability of user guides. Iconic Linkage is a writing strategy that potentially allows users to work more quickly and effectively and which promotes better retention of information. The usefulness of Iconic Linkage was tested in a laboratory-based usability study that combined: 1) objective task-based evaluation; and 2) users' subjective evaluations of a software program used in recording parliamentary debates. A post-test survey designed to test subjects' retention of information contained in the user guides was also administered. The study shows that Iconic Linkage significantly improved usability of the user guide: in all tasks, subjects worked more effectively and made fewer mistakes; while in the three timed tasks, subjects completed the tasks much more quickly. Subjects also gave higher ratings for the software and their retention of information was noticeably improved.

John Daigle on RoboHelp 7

Daigle, an Adobe community expert for RoboHelp, shares his reaction to the RoboHelp 7 sneak peak, and also explains the main features RoboHelp 7 will have: drag-and-drop functionality across the topics, double-byte language support for translation, the ability to have multiple topics open at the same time, snippets with graphics, removal of kadov tags, automatic breadcrumbs, and tighter integration with other Adobe products. Daigle speculates on reasons for Adobe's lack of transparency, and comments on the globalization of Adobe's development for RoboHelp.

Audacity Tutorial: How to Record and Edit Audio with Audacity

Audacity is a free cross platform multi track audio editing program from Sourceforge.net. It will let you record, edit, and mix an unlimited number of tracks. Audacity runs on Windows (98 through XP), Mac OS X, and Linux.

Automating Production with WebWorks AutoMap

WebWorks AutoMap is an extremely useful tool for performing unattended documentation builds. Out of the box, AutoMap can generate reasonable documents. By adding the power of scripting, the results can be amazing.

Best Practice Flare: High Definition PDF

Having introduced the concept of high definition PDF's output straight from Flare's source files with minimal post-production, we can now start to dig into the technologies that are used to produce it.

Flare 5: Adding Advanced HTMLHelp Features

Flare current provides the majority of HTMLHelp settings, and does this in a much more flexible way that HTMLHelp workshop does. Particularly useful are the WYSIWYG help window size and potitioning. However, there are some advanced HTMLHelp settings (such as advanced help, or remembering the users last help settings) that are not currently available.

The Future of RoboHelp?

The RoboHelp help authoring tool is now entering its thirteenth year of existence. That's a remarkably long existence for any software title. In that time period, we have seen an amazing expansion of the software industry throughout the 1990s and an equally amazing retraction due to the bursting of the Internet bubble. Making its start in the tiny offices of Blue Sky Software in LaJolla, California, RoboHelp grew into an extremely profitable product. It is also a market leader—having capturing some two-thirds of all Help authoring tool sales. During the Internet bubble years the company changed its name to eHelp, but RoboHelp continued to be its flagship profit center. In 2003, eHelp (and RoboHelp) were acquired by one of the leading providers of web tools—Macromedia. Now it appears that the end may be approaching for RoboHelp.

Does a Good User Interface Obviate the Need for Documentation?

This question was raised on a programmer's group recently and I was intrigued. The programmer's point was that with many web applications these days there is no print documentation distributed to end users, and even if it existed, many users won't read it although this makes me wonder who's buying all those how-to books I see in the bookstore. The programmer suggested that applications should be designed without documentation and wondered about the impact that would have on design.

Writing Documentation and Help for Eclipse Projects and Plugins

Eclipse is an open-source community. One of its primary projects is the creation of 'an extensible development platform...for building software.' This platform takes shape in the Eclipse workbench, a Java-based IDE (Integrated Development Environment).

XML-Based Documentation Using AurigaDoc

A review of an XML-based documentation tool.

How to Choose a Good Instructional Book about OpenOffice.org

If the success of an open source project can be measured by the number of third-party books about it, then OpenOffice.org is thriving. Not only is OpenOffice.org represented by a dozen books and pieces of training material on Amazon.com, but interest in OpenOffice.org is widespread enough that each of the books is geared to a slightly different audience. This article gives an overview of four of the current OpenOffice.org books, ending with a suggestion of which to buy for your own needs.

Read and Write DocBook XML Using OpenOffice.org

The project goal is to explore the possibility of using OpenOffice.org as a WYSIWYG editor of XML content. The principle is to edit structured documents using styles. These styles are then transformed to XML tags on export.

Cross-Referencing Step Numbers in Word

If you are like most technical writers, your procedures have automatically numbered steps (whether in tables or text), Microsoft Word provides two relatively simple ways for you to cross-reference a step number.

Creating Multimedia Hardware Procedures with ShowMe How

Learning the correct steps to install or remove a computer component, such as a memory module, can involve, at best, hands-on instruction or, at worst, only written instructions. To increase the likelihood that customers and service personnel will be able to perform correctly the hardware service procedure for each fieldreplaceable component, Sun MicrosystemsTM now ships high-quality multimedia of removal and replacement procedures, called ShowMeTM How, on CD with each UltraTM Workstation and Enterprise Workgroup Server.

RoboHelp Office v.3x: the Good, the Bad, and the Indifferent

Overall, in my experience, writers and programmers prefer to use RoboHelp to create and maintain Help systems because the application has fewer issues with the Internet and programming platforms. In fact, for this latest version Of RoboHelp, I have only one minor complaint. Here is a summary of my findings.

Technology and Management Issues in Implementing Online Documentation

This workshop explores how traditionally trained technical communicators can help their companies make wise investments in authoring and delivery software for online documents, explore the potential of technology currently available, and ensure that their technology choices don't lead to dead ends.

Software Usability and Documentation

This article shows how a user-centred approach to software design can reduce the requirement for documentation. It lists Jakob Nielsen's usability heuristics, and for each one, shows how following the heuristic can reduce the requirement for user documentation.

Documenting Entertainment Software: The Mixed Challenge of Simplicity and Sophistication

The challenges of documenting entertainment software are in many ways the challenges of all technical communicators. We strive to make the interface intuitive and the documentation interesting and easy-to-read. Although the nature of the world of entertainment may suggest that our task is simple, the breadth of our audience and the depth of our goals makes it more sophisticated than it looks. We must be as imaginative as our users, recognize the emerging dimensions of multimedia, and create with the constraints of low retail costs, small teams, and fast-paced deadlines.

From Good to Great—: The Finer Points of Writing User Documentation

A few years ago, the NeXT user publications group was handed a charter to create casual books with personality. We were also told to condense the user documentation for an entire operating system and several bundled applications into 300 pages. And of course we had the top priority of creating accurate, complete, and easy-to-use documentation. To our delight, these goals ended up being mutually compatible. The keys? Task orientation, flat hierarchy, carefully crafted page design, illustration, and a casual, intelligent tone. We also broke some 'rules'! (Caution: Some of the following material may seem radical to seasoned traditionalists.)

Publishing Documentation in Microsoft Word: Don't Do It!

To save costs, many small businesses take the do-it-yourself route to publishing product and support documentation. The tool of choice is often Microsoft Word - after all, you probably already have a copy of it and know how to use it reasonably well. But while using Word to develop your materials is an acceptable choice, using it to publish documentation is not! Read on to learn some of Word's shortcomings as a publishing method, and what alternatives are available.

What It Takes to Document America’s Best-Selling Tax Software

Because both the TurboTax Deluxe software program and the federal tax code are redesigned every year, preparing TurboTax Deluxe’s raft of documentation demands a management approach that emphasizes planning, teamwork, task dependencies, and an elusive mix offlexibility and clearly defined project ownership.

A Document Management Case Study: QLD Dept of Housing

How a new spin on document management software helped revolutionise customer service at the Queensland Department of Housing.

Applying Computer Analysis and Design Techniques to Document Component-Based Software

Facing the challenges involved in developing documentation for component-based software (for example, object-oriented technology, intelligent agents, and distributed computing) requires a documentation strategy based on the same processes and methodologies used by such technologies. These strategies need to be adapted to meet documentation, rather than coding needs. Developing this strategy now, as component-based technology is still maturing, will help technical communicators keep pace.

What Is RoboHelp?

RoboHelp is an authoring tool sold by eHelp Corporation (formerly Blue Sky Software). In an easy 'WYSIWYG' format, it allows you to organize information and create pathways and interactive links so a user can find desired or necessary information (and the user can do so in a non-linear intuitive way that is helpful to learning).

Going Online: Selecting the Right Tool

There are numerous tools that you can use to create online documentation. However, each tool has its strengths and weaknesses, and each is more appropriate for some types of information than others. This workshop explores many issues of online documentation tools: Why go beyond Windows Help? Which is better: HTML or Adobe Acrobat? What tools support cross-platform presentation? When should you use Workgroup tools such as Lotus Notes or Folio? When does SGML make sense? How to utilize a!ocument databases? When to use Management tools? Real examples developed using these tools will be given throughout the session. Participants will leave with a clear understanding of the pros and cons of each.

Implications for Writers Documenting Object-Oriented Projects

Object-oriented (OO) projects bring with them new technology and new processes. While programmers focus on the OO methodologies governing design and implementation of program code, writers must struggle to adapt to a very different kind of development cycle. To avoid chaos, development teams must explicitly define their processes from the start.

Ten Misconceptions about Software Documentation

Presents ten misconceptions about software documentation that may have contributed to the persistence of poor documentation.

Help Authoring Tools: a Comparison

The purpose of this article is to give a rough evaluation of the various help authoring packages.

"Try Before You Buy" Help Authoring

Help authoring systems can prove to be a fairly expensive purchase especially for the freelance writer. Luckily, most publishers allow you to try out demonstration versions of their software before you commit yourself to buying. As well as demos of commercial applications, you can find some very high quality shareware and freeware products.

Using RoboHelp to Develop a Simple Web-Based Tutorial

Many technical communicators are tasked with converting user manuals and other documentation written in Adobe FrameMaker into online help using eHelp (formerly Blue Sky) RoboHelp. The problems they face concern not only going from FrameMaker to RoboHelp but also how to put the content in a form that is effective for online help. The solution is not difficult, provided the writer follows a methodical approach.

Screen Captures in Software Documentation

While screen captures are the most widely used illustrations in manuals, there is almost no literature on their role and design. In this paper we draw together practice, theory and empirical research to advance a taxonomy that identifies these roles and designs. We suggest that screen captures in software documentation can help the user to switch attention, develop a mental model of the program, verify screen states, and identify and locate window elements and objects. Four important design areas (coverage, positioning, size, and cueing) are distinguished and empirical findings discussed. Research has substantiated the claim that screen captures speed up task completion, but others have yet to be proven. We believe that a more refined approach, afforded by the taxonomy, is likely to improve practice and research, and yield strong evidence supporting the use of screen captures in software documentation.