Using RoboHelp to Develop a Simple Web-Based Tutorial

RoboHelp is a top application for developing online help. It is also used for developing Web-based help, such as JavaHelp and RoboHelp's WebHelp. Besides being used for online or Web-help, RoboHelp can also be used to develop simple tutorials.

Kurtus, Ron. School for Champions (2001). Design>Documentation>Software>Adobe RoboHelp

Using Usability “Use Cases” in Documentation Planning  

This workshop presents an introduction to use cases - a planning tool which can be used for capturing a future documentation system's functional requirements as well as the overall information requirements of end users. You learn what a use case is and what recommended guidelines there are for creating use cases. You also learn how use cases are applied in the documentation development process as a whole.

Nurminen, Mary and Leena M. Rasinaho. STC Proceedings (1997). Presentations>Documentation>User Centered Design

A Visual Guide to Document Design and Layout  

Technical publications departments in their infancy seem to have great difficulty producing documentation that is well designed and consistent in appearance throughout all documents. As the department matures, it attempts to "consistify" the appearance of the documentation, but, unless there is an experienced template designer on board, this is often a drawn-out process involving focus groups and much squabbling. Once the design is complete, however, it tends to be nearly identical to the templates designed by every other technical publications department in the world. Aside from a handful of design features that distinguish the look and feel of one company's documentation from that of its competitors, everything else is pretty much the same. Whether the focus group spends six months or two years designing templates, they all discover that a well-designed user guide contains some specific and standard design elements.

Amott, Lyndsey. Docsymmetry (2003). Resources>Style Guides>Design>Documentation

Visual Vocabulary Three Years Later: An Interview with Jesse James Garrett

This interview focuses on Jesse James Garret's Visual Vocabulary, a site architecture documentation standard.

Brown, Dan. Boxes and Arrows (2003). Design>Documentation>Information Design>Web Design

What Do Manuals Say About Your Company?  

According to the Consumer Electronics Association, product returns represent a $10 billion-dollar-a-year problem for the consumer electronics industry. Technical support costs are spiraling (even with the migration to off-shore providers) while consumer satisfaction with this support is plummeting. New technology and expanded offerings to a stabilized market are increasing competition. What can manufacturers do to help combat these problems? Better consumer manuals are a start.

Manual Labour (2003). Articles>Documentation>User Centered Design

When Products Become Easy to Use, What's Next for Writers?

People who follow the right trends will someday lead them. Such an opportunity now lies in the hands of technical writers, as the computer field moves toward standardized, graphical, easy-to-use interfaces.

Oram, Andrew. Boston Broadside (1991). Articles>Usability>User Centered Design>Documentation

Where Is the Instruction in Online Help Systems?    

One of the ironic things about online help systems is that they are very often not helpful and even increase the user's frustration and stress level. This increased frustration sometimes results in the rejection of the software. One solution is to increase the effectiveness of online help systems by designing them from an instructional design perspective. Some of the things we can provide users include: imperative, task-focused procedures; graphic feedback; access to redundant instructions; links to tutorial practice; philosophical and conceptual explanations for 'why' they are completing specific tasks.

Pratt, Jean A. Technical Communication Online (1998). Articles>Documentation>Instructional Design>Online

Where is the Instruction in Online Help? Designing it Right the First Time  

One of the ironic things about online help systems is that they are very often not helpful and even increase the user's frustration and stress level. A consequence of this increased frustration sometimes results in the rejection of the software. One solution is to increase the effectiveness of online help systems by designing them from an instructional design perspective. Some of the things we can provide users include: imperative, task-focused procedures; graphic feedback; access to redundant instructions; links to tutorial practice; philosophical and conceptual explanations for “why” they are completing specific tasks.

Pratt, Jean A. STC Proceedings (1997). Presentations>Documentation>Instructional Design>Help

Why Game Documentation is Essential to a Satisfying User Experience

Documentation and information organization are an integral part of video game construction. The video game industry may be one of the directions technical communicators will move toward in the near future.

Peterson, Martin. Usability Interface (2004). Articles>Documentation>User Experience>User Centered Design

Write Once, Use Many: Why and How We Make Product Information Modular  

Faced with growing demand from customers for specific courses, addressing only their needs, in very short time-frames, we had to re-examine the way we worked. Patching together one-shot customized coursework was labor-intensive for a non-homogeneous and unsatisfactory result. Each new customer request required repetition of the same amount of effort. With reduced turnaround time and dwindling human resources, a solution had to be found.

McClelland, Patricia J. and Alison Bourdel. STC Proceedings (1993). Articles>Documentation>Information Design>User Centered Design

Writing Web Documentation

Your product is almost ready for release. You're about to pat yourself on the back when you realize that you have no user documentation! Panic sets in.

Nichols, BeLinda. Webmonkey (2000). Design>Web Design>Documentation

XML and Documentation  

XML provides a robust, non-proprietary, and verifiable file format for the storage and transmission of text and data both on and off the Web. XML removes the complexity of SGML, making it easier to define your own document types, and to write programs to handle them.

Bokil, Manoj. STC India (2003). Articles>Documentation>Information Design>XML

"Yes, But Does it Scale?": Practical Considerations for Database-Driven Information Systems    

This paper explores the process of designing and implementing a database-driven system of online documentation, and putting it live on the web for customers to use. Using real-life examples, it discusses practical considerations for balancing performance, scalability, and reliability.

Russell, John. ACM SIGDOC (2001). Presentations>Information Design>Documentation

Structured Writing, Structured Documentation: What and Why?

A brief comparison of two often-confused concepts.

West, Mike. MBWest.com (2007). Articles>Documentation>Information Design

User-Guide-Driven Development

In my work with Bumblebee I use an approach I call 'User-Guide-Driven Development,' or UGDD for short. The mechanics of UGDD is similar to that of Test-Driven Development (TDD), but before I write the test for a feature, I write a snippet of the user guide describing the feature I am about to implement.

Brolund, Daniel. Thoughts of a Goldfish (2008). Articles>Documentation>Usability>User Centered Design

The Almighty Thud

If you document everything, you are giving everything an equal weight. Do that for a complex system, and you are buried in detail. In any system there are some aspects that are more important than the others, key aspects of the system that once understood, will help someone to learn more. The art in documentation is to find how to document these aspects as clearly as possible. In this you emphasize these areas, and leave the details for the code.

Fowler, Martin. Distributed Computing (1997). Articles>Documentation>User Centered Design>Minimalism

Users Read Help Manuals Like an Encyclopedia, Not a Novel

Users turn to help to look for a specific question, just as someone consults an encyclopedia for a specific question. No one reads the entire encyclopedia/manual, nor is anyone expected to. Well-written encyclopedias allow users to find information through indexes, tables of contents, alphabetical organization, and search fields.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Documentation>User Centered Design>Help

Documenting User-Centered Design Best Practices

When initiating or expanding the role of user-centered design (UCD) in an organization, consider documenting UCD best practices as they fit within existing processes and the best practice of other areas. Such documentation communicates the role and value of UCD throughout the organization in terms familiar to your organization. Because what best practices means varies from company to company, there is no single way to do this. Here are some questions to consider.

Bachmann, Karen L. STC Proceedings (2008). Articles>Documentation>User Centered Design>Policies and Procedures

Has Anyone Used Your Product

Before you release a product, have some people use it. From these "test users" get solutions to problems, tips and knowledge that would help your real-life Users. Put that information in your User Documentation, and on your product support website.

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

Classic Computer Manuals from Apple and IBM

Apple's first user manual was largely the creation of Ronald Wayne, Apple's third founder, recruited from Atari by Steve Jobs for a 10 percent stake in the new company. Wayne not only wrote the entire 10-page booklet, he also drew the intricate cover logo depicting Isaac Newton beneath an apple tree.

Honan, Mathew. Wired (2008). Design>Documentation>Technical Illustration>History

Information Mapping

Information Mapping is a proprietary method for the analysis, organisation, and presentation of information. It is based on the needs of the users and their purpose in using the documentation. Information Mapping has three parts: analysis, organisation, presentation.

Unwalla, Mike. TechScribe (2007). Articles>Documentation>Information Design>Standards

The Changing Face of Technical Publications: Aberdeen Group's Topic-Based Authoring and Customization Strategy Guide

Often conflicting pressures to produce communications that better fit customer demands as well as stay within tightening constraints on budgets and schedules are leading many technical communications organizations to a topic-based approach to authoring. In fact, 58% of participants in Aberdeen Group's October 2008 DITA and the Technical Communicator’s Transformation study report that they currently follow author content in a topic-based manner, with a vast majority of those remaining planning to implement one in the future. A topic-based approach promotes greater content reuse and is seeing a considerable impact on the authoring efficiency of technical communications projects today. The benefits of topic-based authoring can be compelling, with findings from the The Technical Communicator’s Transformation study indicating that when pursued the right way, topic-based authoring can have a broad range of benefits, enabling an organization to meet authoring and localization cost targets as well as documentation quality expectations, among others. However, as the adoption of this approach spreads, the advantages seen by today's leading organizations will flatten out. This Sector Insight provides a guide for current adoption of topic-based authoring and those still considering it; outlining the changes that are expected to take place in as topic-based authoring goes mainstream.

Jackson, Chad and David Houlihan. Aberdeen Group (2008). Resources>Documentation>Information Design>Technical Writing

Reviewing Wiki Documentation via Crucible

I have been playing around with Crucible, Atlassian’s peer code review tool. The latest version of Crucible allows you to review Confluence wiki pages. This is a new feature, so I decided to try it out. Also, I was wondering why you might want to use an independent tool to review a wiki page, when you could instead just add comments to the page or update the page directly.

Maddox, Sarah. ffeathers (2009). Articles>Web Design>Documentation>Wikis

So, You Want To Screen Capture, Huh?

Here's a quick tutorial about screen captures, thus the title. If you're not sure what a screen capture is, then think about the pages you've seen lately. Maybe some of them have had specific sections of the desktop or a program made into an image. It was almost as if they captured part of the screen as an image.

Burns, Joe. HTML Goodies (2004). Articles>Documentation>Graphic Design>Screen Captures