September 2010
By Nicoletta A. Bleiel

Nicky Bleiel is the Lead Information Developer for Doc-To-Help. She has 15 years of experience in technical communication; writing and designing information for software products in the documentation, media, industrial automation, simulation, and pharmaceutical industries. She is a Director at Large of the Society for Technical Communication. 

Blog: “Technical Communication Camp” 

Evaluating software documentation projects quickly

Often when we start a new job, or are dropped into an existing software documentation project at our current job, getting up to speed is overwhelming. This article suggests steps to quickly assess the situation, develop a plan, and begin writing.

Learn the landscape

First, you need to find out the background of the project – its state, the team, and the documentation standards used.

Project status
Most software projects will fall into one of these seven categories:

  • A new product that is still in development, with no user documentation
  • A new product that is complete (or nearing completion), with no user documentation
  • An existing product with little documentation
  • An existing product with documentation
  • An existing product that is in transition to new user interface or other major change
  • An existing product in maintenance mode/New version in process
    Product is in maintenance mode

You need to find out what category your project fits into, and also what specifications or requirements exist (if any). Verify with subject matter experts (SMEs) that those documents are up-to-date.

If any end user documentation exists, you will review it in the planning phase, after determining what deliverables and topics you need. At that point you will know what is missing, as well as if topics need to be rearranged or restructured.

The team
There are several  important things to know about your team in addition to who is on it: you need to find out which ones are the SMEs, who are the SMEs outside the team, and which software development methodology they are using.

By “team” I mean your cross-functional project team, not the group of people you might belong to in the organizational structure. Your project team could be a combination of any of the following: project managers, product managers, business analysts, quality assurance people, technical support staff, and software developers. It is important to discover the SMEs quickly and let them know your role in the project.

There are a number of software development methodologies. Waterfall and Agile are the most common, but there are different variations of both, and each incorporates a number of philosophies. After you find out the methodology being used, learn all you can about it (if you don’t already know it), but keep in mind that it is unlikely that the methodology is being followed to the letter. You need to discover the deviations at your company and adjust accordingly. You may even find yourself on a team that does not put a label on their process at all. In that situation, it may take a little longer to decipher where you fit into the process.

A documentation project needs standards, so setting up the ones for your project – or finding out what your company or the project already uses and documenting it can save time. If there is an internal style guide, that is a great tool, but sometimes it doesn’t contain the following standards (if it does not, add these when you have time): current project templates / cascading style sheets and their locations; source control method; who provides the context IDs for context-sensitive help; the rules around screen caps and graphics (file type, DPI, style for callouts, etc.); and video requirements (output type, length, audio, caption style, opening/closing boilerplate information). It is very useful to have a copy of the Microsoft Manual of Style on hand.

Other standards include your toolset: your Help Authoring Tool (HAT), screen capture tool, video creation tool, etc. If you don’t have the tools you need, decide what features you need and start investigating. The HAT-Matrix would be a good place to start:

You’ve surveyed … now plan

Now that you have the background information, you can plan and then begin writing. Advance planning saves writing time, because you have documented what you need, organized it, and determined how it should be structured.

If the product currently has user documentation, you can use these steps to determine if it needs rewriting or restructuring, what is missing, and if other deliverables are needed.

Determine deliverables
Decide what your deliverables set will include. List everything, even items that may have to wait for future releases. Your list could include the following: online Help, manuals, quick reference guides, videos, release notes, embedded Help, knowledgebase articles, tooltips/expanded tooltips, and more.

Keep in mind the following when determining your deliverables s

  • What are the end-users workplace constraints? (available from field observation/research, and SMEs)
  • What are your end-users preferences for information?
  • Does this release have any special circumstances? (A new interface, for example. In this case, you may need to add quick reference guides to explain what has changed to existing users.)
  • SME input

In addition, determine:

  • What will be the outputs for each deliverable? (For example, you may need both HTML Help and Web-based Help.)
  • Will you need different versions of the same deliverable for different audiences? (For example, a different user guide for the pharmacist, nurse manager, and nurse.)
  • What will be the file names for each deliverable? Get approval for each one. Changing file names at the last minute can introduce errors (installation scripts and hyperlinks can break.) Try to leave the year out of the names if possible.
  • Where will the deliverables be stored? Internally for installation builds, and on the web; you should put as much content on the web as you can – it makes it easier for users to find it, makes continuous publishing possible, and is the most efficient way to link to it – especially videos (since their file size makes them hard to include in installs). Highly sensitive deliverables cannot be stored on the web, of course, unless your company has a special firewalled area for customers.
  • How will they be accessed from the interface? Will there be a Help menu and buttons? Will there be context-sensitive Help on dialog boxes? Could any deliverables be made available directly from the Start page of the application? The easier it is to find documentation, the more likely it will be found.
  • What is the social media strategy for the software? If your company has a presence on Twitter, Facebook, LinkedIn, or other social media space, you may want to consider using it for creating a community, gathering feedback on documentation, making announcements, or some other purpose. If your company does not have a social media presence, you may want to consider developing a documentation strategy and implementing it.

Divide and conquer
The hub of your project — the online Help and/or manual — will include topics that fall into four categories:

  1. Functionality (what the software does; how it solves user problems),
  2. Housekeeping (system requirements, end user license agreements, installation instructions),
  3. Reference (glossaries, tutorials), and
  4. User Interface (UI); these topics are a subset of Functionality topics and include information that will be accessible directly from the UI – such as context-sensitive Help on dialog boxes, embedded Help panes, etc.

Determine which topics (existing and non-existing) belong in each category and store this information on a spreadsheet, or use another method you prefer.

Seeing the topics grouped this way will make it easy to name them logically and consistently, and spot any internal terminology.

Then develop (or adopt) topic architectures. Topic architectures are pre-defined ways to structure your topics. You can create your own, or use ones that already exist. Determine which architectures you will need (for example: Functionality Overview topic, Dialog Box topic) and sketch out the structure of each. Using architectures make writing much easier because you will know what is required for each topic, so you will avoid redundant information between topics, as well as accidentally omitting important information.

Example: Functionality Introduction Topic

This architecture is used for every topic that introduces major piece product functionality.


  • Title
  • “Why is this important?”
  • Overview
  • “How to”/Tasks
  • Video (if available)
  • Related Topics (Generated by HAT + additional added)  

Develop your project architecture
Now you can organize all of your topics and create the architecture for your project. Start with your “buckets” of information (Functionality, Housekeeping, Reference, and User Interface). Sort them into a logical table of contents; flag the topics that are also the context-sensitive Help for dialog boxes.

You can have more than one architecture for your project, particularly if you are single-sourcing to different outputs using conditions. In that case, you should still start with an architecture that includes everything, then flag the topics that only belong in specific outputs.

Write and deliver

Since you have the project background, as well as your plan, you can begin writing your topics, tooltips, tutorials, quick reference guides, and other deliverables, and creating videos, podcasts, and other media.

The great thing about analyzing your project this way is that it works for both existing and new projects. You don’t have to discard existing topics and deliverables; you just have to determine where they fit into the project and the adjustments that need to be made.

Page 1 from 1
#1 Sanjib Dasgupta wrote at Wed, Jun 08 answer

Excellent article. Very detailed. Loved it.