Documenting Software Applications

As a result of more than 15 years working as a Technical Writer on a variety of industrial sectors I came up with road map to develop accurate and friendly documentation for technical audiences. In this article I would like to share some of my experience in producing a variety of User Guides and Online Help systems for software systems.

I have devised a road map to help anyone get a successful documentation project review. 

Stage 1 - Development Strategy

Stage 2 - User Requirements

Stage 3 - Documentation Project Requirements

Stage 4 - Define Your Documentation Project

Stage 5 - Design Approach

Stage 6 - Documentation Production

Stage 7 - Documentation Reviews

Stage 8 - Documentation Delivery

Stage 9 - Documentation Management

The following sections will describe in detail each stage according to my experience in the field.

Stage 1 - Development Strategy

• Background Information Gathering.
• Define the scope of the documentation project.
• Define documentation project requirements.
• Define documentation production strategy.
• Define user requirements (refer to Stage 2). 

Stage 2 - User Requirements

•  What is the target audience?
  a) People already familiar with the system? Upgrade users?
  b) Admin users?
  c) Operator users? With/Without technical background?
• What the end user is expecting to get? A procedural or a how to guide?
• Is there any workflow in use to based upon?

<In Progress>

Stage 3 - Documentation Project Requirements

•  Define your Tools for the project:
  a) Image manipulation tool - in my case I prefer my old PaintShop Pro, which is portable and very easy to use, particularly to create/edit buttons, menu options, toolbars, etc.
  b) HAT tool - in my case I prefer Adobe RoboHelp.
  c) You may need a digital camera to take photos of equipment - I use my iPhone which provide the definition and sharpness I need most of the time.

<In Progress>

Stage 4 - Define Your Documentation Project Environment

•  Define your Project deliverables and schedule in sync with the SDLC.
• Setup your Project in RoboHelp (or your preferable HAT).
• Define your Project folder in the local drive and the back on the Network.
• Define your Project repository (use MS SharePoint if you do not have other CMS).
• Define your Project file name convention for documents and images (if your company don't have one).
• Require a copy of the software to run in your local machine, if possible, to make easier to test drive it and take required screenshots using your own tools.

 <In Progress>

Stage 5 - Design Approach

• Gather Information on Company Standards for Documentation.
• Gather Information on Existing Technical Documentation.
• Gather Company Requirements and Documentation Schedules.
• Check Existing Templates Requiring Improvements to meet the Software Project Requirements.
• Create New Templates as Required to Meet Project Requirements.
• Conform Document Layout Matching Corporate Image.
• Add Review History to the document.
• Add copyright notices.
• Add conventions and signs used in the document. 

Stage 6 - Documentation Production

• Fix document template styles.
• Work out the manual content outline.
• Prepare a Table of Contents, Table of Figures and Table of Tables.
• Take notes about requirements to start the software.
  a) It requires previous configuration?
  b) It requires any previous preparation?
  c) It requires test sample data (in case of databases)?
• Start to run the software by yourself to understand its functionality and to capture required screenshots to support your procedure descriptions.
• Notice related functionality between the GUI and the hardware and take notes about synchronous/asynchronous running.
• Take notes about error/exception messages and related procedures to work around errors or faults.
• Re-run every procedure against the software and hardware functionality. Take notes on work arounds and fatal errors.

<In Progress>

Stage 7 - Documentation Reviews

• Get a list of appointed reviewers from your Supervisor.
• Provide to each reviewer guidelines on how to mark up required or suggested changes in the document. Mention to them that they should comment pointing to a solution, not placing question marks. Also ask them about their preferences to comment on PDF or in printing.

<In Progress>

Stage 8 - Documentation Delivery

•  Contact the Marketing or related department about the final look and feel of the manual, asking for input.
• Prepare the manual for printing (in house or for a Printer house) or to output to PDF.
• Submit proof to whom it may concern.
• Get final approval for delivery.
• Delivery the document to the expected format and medium.

<In Progress>

Stage 9 - Documentation Management

• Select a Content Management System to store your manuals.
• Create a full backup of your project documentation before going ahead with a new project. Place it on a Network or CMS for future reference or use.

<In Progress>

Technical Writing Skills From Experience

Doing this type of analysis repeatedly enables a technical writer to notice things that even an engineer who developed the product may miss. Good technical writers have years of experience writing, re-writing, and then re-writing again to eliminate unnecessary words.

Observing the steps defined above, the TW will be able to:

• Create accurate, concise documentation that enables users to complete tasks independently.
• Organize information so that users quickly find what they need.
• Avoid confusing users with extraneous or out-of-place information.
• Avoid losing users due to inappropriate assumptions about their knowledge and background.
• Reduce support costs.
• Increase customer satisfaction.
• Demonstrate to customers that the guidance they need is accessible and easy to use.

Roadmap to Document Equipment Software Driven

I am a senior Technical Writer working for the private and Government sectors of the IT industry. As a result of one of my recent assignments, which required the development technical documentation for advanced LASER technology, with AWTA, I decided to share with my LinkedIn peers my experience in that area.

For this article, I am proposing a road map to develop accurate and friendly Operating and Technical Manuals for hardware equipment controlled by software systems for technical audiences.

The following roadmap will help anyone get a successful documentation project review. 

Stage 1 - Development Strategy

Stage 2 - User Requirements

Stage 3 - Documentation Project Requirements

Stage 4 - Define Your Documentation Project

Stage 5 - Design Approach

Stage 6 - Documentation Production

Stage 7 - Documentation Reviews

Stage 8 - Documentation Delivery

Stage 9 - Documentation Management

The following sections will describe in detail each stage according to my experience in the field.

Stage 1 - Development Strategy

• Background Information Gathering.
• Define the scope of the documentation project.
• Define documentation project requirements.
• Define documentation production strategy.
• Define user requirements (refer to Stage 2). 

Stage 2 - User Requirements

•  What is the target audience?
  a) People already familiar with the system? Upgrade users?
  b) Admin users?
  c) Operator users? With/Without technical background?
  d) Maintenance technicians?
• What the end user is expecting to get? A procedural or a how to guide?
• Is there any workflow in use to based upon?

<In Progress>

Stage 3 - Documentation Project Requirements

•  Define your Tools for the project:
  a) Image manipulation tool - in my case I prefer my old PaintShop Pro, which is portable and very easy to use, particularly to create/edit buttons, menu options, toolbars, etc.
  b) Word Processor tool - in my case I prefer MS Word for Windows.
  c) You may need a digital camera to take photos of equipment - I use my iPhone which provide the definition and sharpness I need most of the time.

<In Progress>

Stage 4 - Define Your Documentation Project

•  Define your Documentation Project deliverables and schedule in sync with the company project management.

 <In Progress>

Stage 5 - Design Approach

• Gather Information on Company Standards for Documentation.
• Gather Information on Existing Technical Documentation.
• Gather Company Requirements and Documentation Schedules.
• Check Existing Templates Requiring Improvements to Meet Project Requirements.
• Create New Templates as Required to Meet Project Requirements.
• Conform Document Layout Matching Corporate Image.
• Add Review History to the document.
• Add copyright notices.
• Add conventions used in the document. 

Stage 6 - Documentation Production

• Fix document template styles.
• Work out the manual content outline.
• Prepare a Table of Contents, Table of Figures and Table of Tables.
• Take notes about requirements to start the software/hardware.
  a) It requires previous configuration?
  a) It requires any previous preparation?
  c) It requires previous calibration?
  d) It requires test sample materials?
• Start to run the software to understand its functionality and to capture required screenshots to support your procedure descriptions.
• Notice related functionality between the GUI and the hardware and take notes about synchronous/asynchronous running.
• Take notes about error/exception messages and related procedures to work around errors or faults.
• Re-run every procedure against the software and hardware functionality. Take notes on work around and fatal errors.

Note: Keep in mind that a particular formatting care should be taken if the document would be later converted into a different output format, like HTML or Online Help. Particularly for a future Online Help project, keep your styles consistent, well named and structured as you may need to map them against you online help project editor to make importing easier.

Stage 7 - Documentation Reviews

• Get a list of appointed reviewers from your Supervisor.
• Try to identify with your Supervisor the expected review area that will be covered by each reviewer. For instance if the reviewers will target:
  a) proofreading,
  b) layout/look and feel, or
  c) content's accuracy in particular.
• Provide to each reviewer the option on how to markup the document (preferably in hard copy or PDF).
• Provide to each reviewer guidelines on how to mark up required or suggested changes in the document. Mention to them that they should comment pointing to a solution, instead of placing question marks. 
• Take notes on the date the document was passed to each reviewer. Better still is to create a document section entitled Review History in a table format including the reviewer's name and date of the draft delivery. If in hard copy, always stamp or write down on the top right corner of the first page the Draft # and delivery date with your initials.
• Give a week for each reviewer and start to follow up how they are progressing, making sure they know the management's expected completion date.

<In Progress>

Stage 8 - Documentation Delivery

•  Contact the Marketing or related department about the final look and feel of the manual, asking for input.
• Prepare the manual for printing (in house or for a Printer house) or to output to PDF.
• Submit proof to whom it may concern.
• Get final approval for delivery.
• Delivery the document to the expected format and medium.

<In Progress>

Stage 9 - Documentation Management

• Select a Content Management System to store your manuals.
• Create a full backup of your project documentation before going ahead with a new project. Place it on a Network or CMS for future reference or use.

<In Progress>

Technical Writing Skills From Experience

Doing this type of analysis repeatedly enables a technical writer to notice things that even an engineer who developed the product may miss. Good technical writers have years of experience writing, re-writing, and then re-writing again to eliminate unnecessary words.

Observing the steps defined above, the TW will be able to:

• Create accurate, concise documentation that enables users to complete tasks independently.
• Organize information so that users quickly find what they need.
• Avoid confusing users with extraneous or out-of-place information.
• Avoid losing users due to inappropriate assumptions about their knowledge and background.
• Reduce support costs.
• Increase customer satisfaction.
• Demonstrate to customers that the guidance they need is accessible and easy to use.