Policies and Procedures 1995 PIC Meeting  

This session is intended for those interested in (a) policies and procedures as a subject, (b) networking with others concerned with policies and procedures, (c) learning about this PIC, (d) influencing the direction of this PIC, or (e) listening, commenting, or volunteering. The first portion of the meeting will briefly review the PIC's history, mission, membership, budget, teams, goals, and progress. The second portion will be open to discuss new business.

Urgo, Raymond E. STC Proceedings (1995). Articles>Documentation>Policies and Procedures

A Process Model For Creating Accessible End-User Documents  

Electronic information products can be made accessible to blind and low-vision individuals. This is easier to accomplish with thorough planning and execution. This paper describes a five-step model for creating accessible documentation. The steps are (1) Preparing a source file (2) Producing accessible output, (3) Testing output for accessibility, (4) Modifying a source file if needed, and (5) Modifying a production process if absolutely necessary.

Herring, Richard D. STC Proceedings (2005). Articles>Documentation>Writing>Technical Writing

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.

Smart, Karl L. STC Proceedings (1993). Articles>Documentation>Instructional Design>Software

Adapting Traditional Editing Practices for Online Documentation  

Technical editors are possibly best known for their abilities to transform information with format, content, grammatical, and mechanical problems into coherent, concise, understandable, and usable documents. Editors must not only provide such services for the information authors, but they must also understand and support users' needs and expectations. This presentation gives editors an approach to editing online documentation that is rooted in traditional editing practices.

Fink, Bonnie L., Carol Gasser, Jennifer Giordano and Beth A. Williams. STC Proceedings (1998). Articles>Editing>Documentation>Online

Add One Egg, a Cup of Milk, and Stir: Single Source Documentation for Today

What happens when the software firm you work for decides it will not deliver large printed manuals any more? Then the request comes to put everything online. Six months later, user profiles shift to the World Wide Web and you're asked to deliver HTML. In the future, a database of SGML information chunks may let us deliver anything, any which way. Today, we must devise a system that allows us to 'author once, publish many'. Such as system is crucial for software and hardware documentation. The method I chose was to go from FrameMaker to Acrobat .pdf files to HTML. I wrote in Adobe FrameMaker, then converted to .pdf files with Adobe Acrobat, and converted FrameMaker to HTML files with Quadralay WebWorks Publisher. But while we're waiting for the future, just learning SGML and diving deep into DTDs alone could be a mistake. SGML is a language which sets out structure, and most of us are concerned with content. Enter Information Mapping, or information types of your own devising. Identifying chunks of information such as a procedure for changing the default printer is extremely important. If we then mark each chunk for an index and record its type and title, we've also got the keywords for a future database.

Stieren, Carl. Simware (1997). Articles>Documentation>Single Sourcing>Adobe FrameMaker

Adding Life to Your Documentation  

Suggests several techniques technical writers can use to enliven their writing and improve their documentation.

Potsus, Whitney Beth. Intercom (2003). Articles>Documentation>Writing>Technical Writing

Adjust Your Documentation Plan for .NET  

Developing in the .NET environment requires internal documentation changes. Learn how to adjust your documentation plan so that it encompasses additional elements, such as the needs of mobile users.

Kelly, William T. TechRepublic (2003). Articles>Documentation>Server Side Includes

Adobe Acrobat: Publishing Online Documentation  

Documentation departments are often faced with the challenge of quickly distributing high-quality versions of printed documentation via the company Intranet, the World Wide Web, or CD-ROM. Adobe Acrobat is a simple, cost-effective way to publish documentation for a variety of media and requires little time or technical expertise to produce professional-looking results. Technical writers and web developers can easily use Adobe Acrobat to create portable document format (PDF) files from printed documentation. They can then add links and bookmarks, create an index, produce simple interactive forms, and add multimedia components to their documents.

Ogata, Kerry L. and Thomas A. Witherspoon. STC Proceedings (1998). Articles>Documentation>Online>Adobe Acrobat

Advantage of a Rainy Summer

This article deals, despite the title above, with aspects on handling and checking of technical documentation. I consider these aspects as part of the functionality of documentation besides more conventional functionality such as factual correctness, layout, combination of figures and text.

Rullgård, Åke. TC-FORUM (2000). Articles>Documentation>User Centered Design

Adventures in Screencasting    

How do you best assist users whose learning styles are more visual than verbal? Tietjen discusses the benefits and the how-to of screencasting, a mixture of visuals, audio, and complementary text.

Tietjen, Phil. Intercom (2008). Articles>Documentation>Multimedia>Screen Captures

AECMA 1000D - Goal and Reality

The contribution deals with the transposition of projects on the basis of the AECMA-1000D-specification. The author explains problems which exist outside aeronautics with the application of this specification.

Just, Stefan. TC-FORUM (2001). Articles>Documentation>Standards

Agile Documentation (Using Tests as Documentation)  

Storytelling can make documentation more exciting for both writers and readers. Stories provide context and people tend to remember them. More all-∆around fun when stories are tests.

Gheorghiu, Grig. Business Information Review. Articles>Documentation>Agile>Testing

Agile Documentation with doctest and epydoc

A Test Map is a list of unit tests associated with a specific function/method under test. It helps you see how that specific function/method is being exercised via unit tests.

Gheorghiu, Grig. Blogspot (2005). Articles>Documentation>Agile

Agile Documentation: Strategies for Agile Software Development

When I initially started work on Agile Modeling (AM) I wanted to focus solely on principles and practices for effective modeling but quickly discovered that this scope was not sufficient, that I also needed to consider the issue of how to be effective at the creation and maintenance of documentation too. Some agile models will 'evolve' into official system documentation, although the vast majority will not, and therefore it is relevant to discuss how to be agile doing so.

Agile Modeling. Articles>Documentation>Agile>Extreme Documentation

An Agile Review Process for Technical Documentation

Documentation teams need a fast and effective review process to move forward on their projects and deliver quality, timely content. Reviewers, may they be SMEs (Subject Matter Experts) or key organization authorities, are usually extremely busy and have limited time (or interest) to review documentation. Interesting dilemma, no?

Talbot, Fabrice. LiveTechDocs (2008). Articles>Documentation>Agile>Workflow

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.

Pehrson, Paul and Tom H. Johnson. Tech Writer Voices (2008). Articles>Documentation>Software>Madcap Flare

The Almighty Thud

Why do we bother with models or documentation? They don't execute, and our customers pay us for working code, not pretty pictures. We bother with models to communicate. The idea is that a graphical object model can show how objects fit together more clearly than looking at the source, an interaction diagram can show a collaboration better than figuring out the call path from several class definitions. But so often the design documentation fails in this, and leaves me puzzled on my sofa.

Fowler, Martin. MartinFowler.com (1997). Articles>Documentation>Agile>Extreme Documentation

An Overview of Single Sourcing with an XML Content Management System

Creating an XML-based Content Management System to single-source technical publications is as simple as 1 - 2 - 3. OK, maybe it isn't quite that easy, but this article discusses how it can be done.

Sapir, Rick. KeyContent.org (2004). Articles>Content Management>Documentation>XML

Analysis and Resolution of Problems Occurring During the Production of Manuals  

We produce numerous manuals pertaining to telecommunications and, although we routinely devote much energy to reducing the number of problems occurring during the production process, this time we took up the challenge of eliminating the occurrence of problems altogether. Here, we overview the characterisitics of problems occurring at the company, profile their occurrence by process, and review a few corrective measures.

Konno, Toshiaki, Masanori Takagi and Osamu Tomooka. STC Proceedings (1995). Articles>Documentation>Quality

Analyzing Web-Based Help Usage Data to Improve Products  

This paper describes how user assistance can streamline deliverables and improve product design by analyzing usage patterns from server-based content. We can then base decisions about how to improve deliverables on a thorough understanding of how customers use help content to find information and solve problems. This approach enables user assistance to add more value to both our companies and our customers by creating a three-way dialog between user assistance, the customer, and the product team. It also broadens the definition of assistance to include helping to design products that people can use without the need for instructions.

Raiken, Nancy. STC Proceedings (2005). Articles>Documentation>Audience Analysis>Log Analysis

Analyzing Your Users and Needs Before Creating the Help Deliverables; Interview with Nicky Bleiel

In this podcast, Nicky Bleiel says we should talk to as many users as we can — conducting on-site visits, sending surveys, gathering information from Marketing, Support, and other departments — so we can have a better understanding of our users’ needs and the formats and mediums that will work best for them. After completing this audience and needs analysis, we can then go out and create the deliverables that will best serve our users.

Bleiel, Nicky and Tom H. Johnson. Tech Writer Voices (2008). Articles>Interviews>Documentation>User Centered Design

The Anatomy of a Help File: An Iterative Approach

This article presents an approach to Help file design that focuses on creating a task-centered user experience and accommodates an iterative development strategy. This methodology allows the introduction of user assistance into early test phases--not only getting earlier validation for its accuracy, but also supporting quality assurance testing by serving as the test scripts for interactions with the user interface. This approach can also be a self-contained strategy--that is, one that allows an iterative approach to user assistance development even if the rest of product development operates on a waterfall model.

Hughes, Michael A. UXmatters (2007). Articles>Documentation>Methods>Help

Anything That Can Go Wrong: Lessons Learned from A Decade of Toolkit Documentation  

Writing software toolkit documentation for programmers is a special challenge and opportunity for technical writers. Compared with writing software documentation for lay users, toolkit documentation is more demanding and exacting. Checking facts and finding tiny errors is like riding a motorcycle through a swarm of gnats. However, for me at least, toolkit writing has opened doors to a larger role and greater input into product design. Engineers treat me like a peer and I get to see into their culture. I know my readers and salespeople need me.

van Oss, Joseph E. STC Proceedings (1999). Articles>Documentation>SDK>Technical Writing