Technical Writing & Technical Training Materials

Getting Started in IT

Technical Writing and Technical Training are two great jobs. If you are a teacher seeking to move into the Information Technology industry, you may want to check out technical training jobs. These jobs relate to teaching, as discussed later in this article. 

My first IT job was working as a technical writer, a career I held for about five or six years.  While working as a technical writer I wrote technical documents for the following types of companies: telecommunications (such as Nextel), systems integration (which design and build complex applications), network security, software development, etc. Although the types of documents written are the same, the most challenging part was learning the terms associated with each company type. Telecommunications terminology is very different from systems integration terminology. This is because different company types use different types of technology. For example, telecommunications companies support wireless phones and other similar products. On the other hand, systems integration companies implement systems such as enterprise resource planning (ERP) systems used to run an entire company. 

Technical trainer and technical writer jobs are closely related. A technical writer writes the user's guides, quick reference materials, getting started guides, installation guides and other technical materials. Technical trainers, on the other hand, plan and design training programs. They also write the training materials and they often stand up front and teach students. However, online training is becoming more common so not all technical trainers stand in front of a classroom and teach students. 

Technical Training Materials

While working for a systems integration company (BDM International), I had to assist with developing technical training materials as well as end-user documents. The technical training materials I created were as follows:

1)    Slide Presentation. The Slide Presentation teaches end users how to perform a task.

2)    Lab Book. The lab book includes learning objectives for each chapter. It also provides instructions on how to perform tasks associated with data already in the system. Or, it provides instructions on specific data the user is to add and manipulate. Each chapter concludes with a list of Review questions to reinforce the learning objectives.

3)    Facilitator's Guide. The Facilitator's Guide is written for the instructor. It includes the information (that should be conveyed to students) for each slide in the presentation. It also includes the answers to the Review questions. Typically, technical trainings will include time for the instructor to discuss the Review questions and provide the correct answer.

4)    Survey. Surveys are typically created to gather information the company needs to make training decisions. These surveys are usually handed out about 10 minutes before class ends so students have a chance to complete them and leave class on time.

Technical Documents versus Technical Training Materials

The key difference between the user's guide and the training materials is the user's guide provides general instructions while the technical training materials include instructions about one or more specific records. For example, a user's guide might include a topic called "Adding a Customer Record". This topic would include general instructions as follows:

-------------------------------------------------------------------------------------------------------

1. Log in.

2. Select Add from the Main menu. The Add page displays. 

3. Select Customer from the Add page. The Add Customer page displays.

4. Enter the customer's information (including first name, last name, etc.)
Note: Fields preceded by an asterisk are required and must be completed prior to saving the record.

5. Once you have completed all information click the Save button. The record is saved and the Add Customer page closes.

Note: If you click the Save ​button before you have completed all of the required fields, an error message will display. If this happens click the OK button on the error message. The error message will close so you can access the Add Customer page. Red text (required field) displays beside any required fields left blank.

-------------------------------------------------------------------------------------------------------

The lab book (which is comparable to the user’s guide) will have the Adding a Customer Record lesson. However, the lab book will also include the learning objectives. Below is an example.

-------------------------------------------------------------------------------------------------------

In this lesson you will learn the following:

• How to add a customer records
• How to recognize fields that require information
• How to save a record
• How to respond to an error message.

-------------------------------------------------------------------------------------------------------

The instructions in a lab book are written differently from the instructions in a user’s guide. Below is an example of the instructions in a lab book.

-------------------------------------------------------------------------------------------------------

Instructions:  In this lesson you are going to add Mr. Wyatt Johnson as a new customer. Please follow the instructions below to complete this lesson.

1. Log into the demo account using the following credentials:

User Name: Jane Doe   
Password:  P@ssword22

2. Select Add from the Main menu. The Add window displays.

3. Select Customer from the Add window. The Add Customer window displays.

4. Click in the First Name field. Add the following: Wyatt.

5. Leave the Last Name field blank. Notice that this field is preceded by an asterisk. This means this field is required. However, leave this field blank for now. This will give you an opportunity to see the error message and learn how to respond to it.

6. Click in the Address 1 field. Type the following:  2244 Yellow Stone Park Rd.

7. Click in the Address 2 field. Type the following:  Suite 260

8. Click in the City field. Type the following:  Pasadena

9. Click in the State field. Type the following:  California

10. Click in the Zip Code field. Type the following:  91101

11. Click the Save button. An error message displays, "You must complete all required fields".

12. Click the OK button to close the error message. Notice red text (required field) displays beside the Last Name field because it is required.
13. Click in the Last Name field. Add the following:  Johnson

14. Click the Save button. The record is saved and the Add Customer page closes.

CONGRATULATIONS: You have completed the Adding a Customer Record lesson.

-------------------------------------------------------------------------------------------------------

Notice the lab book provide specific log in information and tells users what data to add. When a system is built and it is determined that training will be provided on that system; the technical trainer usually provides the content that must be added (if applicable) so users can use the system for training. Based on the technical trainer’s request, the developer will create a demo account that can be used for training and/or customer demonstrations. Therefore, more planning is required for training materials then for technical documents such as user’s guides.

In short, user's guides provide instructions so users can perform a task using any data the user wants to add or update, search or delete.  Technical training provides more specific direction by telling users what records to add, edit, delete or search.

User's Guides - Technical Writing

I learned how to write a user's guide by looking at various users’ guides for products on the market. To practice developing user’s guides I would go to www.downloads.com to select and download various types of software  (i.e., change request, enterprise resource planning, customer relationship management, help desk, etc.). The more I practiced; the better I got at organizing the topics. Eventually I came up with a standardized outline that I could use for the user's guide. I only deviated from the standard outline when I had to. Using this rhythm made it easier for users to understand how the topics were organized. This made it easier for users to find information. For example, my table of contents would look as follows:

-------------------------------------------------------------------------------------------------------

Table of Contents

Managing Customer Records

• Adding a Customer Record
• Searching for a Customer Record
• Editing a Customer Record
• Deleting a Customer Record

Managing Orders

• Adding an Order
• Associating a Customer Record with an Order
• Associating an Employee Record with an Order
• Searching for an Order
• Searching by Order ID
• Searching by Customer Name
• Searching by Employee Name
• Editing an Order
• Canceling an Order

Managing Employee Records

• Adding an Employee Record
• Searching for an Employee
• Editing an Employee Record
• Deleting an Employee Record

-------------------------------------------------------------------------------

How it All Adds Up

Although technical writer salaries started out paying $75,000 or more (depending on experience), annually salaries have dropped. Now, on the average, technical writers earn around $75,000 - $85,000 (and that amount may further drop in the coming years). Those who earn salaries in the $90,000s have very strong technical skills and a lot of IT experience. Technical training salaries are still pretty competitive paying around $85,000 to $90,000 annually. A technical trainer with years of industry experience could probably earn more. However, people with that level of experience usually start their own technical training company to target government contracts and earn millions for their knowledge and experience.

Requirements: Writing Use Cases

Use Case Overview

A Use Case is a requirement that directly relates to a user's or system's ability to do something. The something a user does may include creating a record, deleting a record, editing a record, searching for a specific  record, logging into a system, generating a specific type of report, exporting a data, etc. Some projects use user scenarios instead of use cases. However, many projects still use use cases because this type of requirement has been around longer and provides clearer direction when creating requirements. Use Cases are typically included in a document called the Use Case Specification.

Use Case Properties

Use Cases also have properties. A property is text that provides specific information about the use case. For example Use Case Name and Use Case Description are both properties, Following is a list of the Use Case Properties:

ID:  The identify of the use case. Each use case has a unique identifier such as 1, 2, 3, 4, or 1.0, 1.1, 2.0, etc.

Name:  A unique name for the use case. Examples: Add a Customer Record, Update a Customer Record, Mark a Customer Record as Inactive (which is associated with the update task), Search Customer Records, Filter Customer records, Generate a Customer Orders Report.

Description:  This field provides additional information about the use case.

Date: The date the use case was created or updated.

Actor(s): The user group that will be able to perform this use case. For example, user groups can be HR secretaries, HR Benefits Managements, Accounts Receivable Clerks, Desktop Publishers, teachers, principals, students, parents, etc.

Pre-condition: The condition the system is in before the use case is executed. For example the system might be in a "Validated" state if it is about to store data; but was required to validate the data first.

Post-condition: The condition the system is in after the use case has been executed. For example, if the system just filled an order it might be in the "order filled" state.

Normal Flow: This property outlines the steps the user executes to complete the task defined by the use case. For example, Create a Customer Record the user my 1. Log into the system; 2. Select Customer Management (from the menu); 3. Select Create Customer from the Customer Management page; 4. Enter customer information; 5. Click Save to save the record and return to the Customer Management page.

Alternate Flow: This property outlines any alternate paths a user might take to execute the use case. For example, users might perform step 1 from the normal flow. Then for step 2 users may right click and select Import to import a customer record.  Since users are performing a step differently, this is known as a branch. A branch is used whenever users perform the same task (in this case, Create a Customer Record) differently. Step 3 then says "return to step 5. Normal flow". So the alternate flow only outlines were steps differ from the normal flow.

Includes: This property outlines the Use cases this use case includes or uses. To execute the Create a Customer Record use case users must first  "Log into the system," which is also a use case that defines logging in requirements. Whenever users must perform the steps in another use case to complete the current use case; the current use cases uses or includes another use case.

Extends: When a use case extends another use case the extending use case adds additional functionality to  the base use case. For example, a toy manufacturer may have a program where customers (who meet a certain criteria) can use points they've earned to buy beta toys. Ordering beta toys requires different functionality from the functionality required to order regular toys. For example, customers cannot use money or credit cards to buy beta toys--making the payment method different. Customers cannot purchase beta toys from the regular product stock--making the location where toys are stocked different. In addition customers can't backorder or pre-order beta toys. And, customers must meet a certain criteria  to view the available beta toys. Therefore, there should be a use case that supports the functionality to "Place an Order". The "Order Beta Toys" use case would extend the "Place an Order" use case.

Business Rule(s): Many companies establish business rules. Some business rules must be enforced by a system; while other business rules cannot be enforced by a system. If a business rule is to be implemented or enforced by a system; it is associated with the applicable use case.  Examples of Business Rules are as follows: 1. An employee must work for the company for 3 years before he/she can enter a customer order into the system. 2. A Customer Service Manager must approve the order before the products are shipped. (Note that both of these business rules can be implemented by the system.)

Feature(s): The feature is the highest level of requirement. Features are used to group a use case. Examples of features include Generate Reports, Manage Customer Records, Interface With Accounting System, etc.

The Use Case Specification

Use Cases are typically added to a Use Case Specification. The Use Case Specification is a document that includes the use cases along with the property details for each use case. Once the Use Case Specification is completed; it is distributed to the users or user representatives for review and feedback.

Requirements: Understanding the Customer's Vision

Establishing the Vision

One of the most important aspects of designing a system is requirements gathering. A company can have the most seasoned user experience professionals, top-notch developers and exceptional testers that catch every defect. But, will the customer be happy with a beautifully built, flawless product that isn't what was needed? Probably not!

For over 8 years I've worked as a business systems analyst; typically hired as a consultant after a project has failed. And, in most cases, the projects that failed did so because incorrect assumptions were made. And, requirements were then written from a mixture of inaccurate assumptions and customer statements.

The only way to accurately identify customer requirements is to ask questions. Ask questions and let the customer state his/her vision for the implementation. Be sure to ask about business problems and needs that may have initiated the need for the project. You can manage this information by creating a list of business problems and/or needs. Ultimately, all requirements and problems/needs should be managed using a requirements management system such as RequisitePro.

 

Problem/Needs List

1.1 NEED:  Need a dashboard that reflects current sales by region

 

1.2 PROBLEM: Currently, end users are not able to associate a customer order with a region (data can only be associated with a city and state). Should we have the system assign the region based on the city/state? How can we fix this problem?
1.3 NEED:  Need to be able to generate reports for segment marketing. We need to implement a business intelligence solution.
1.4 PROBLEM: All employees can add order records, when only Customer Support should be able to add order records. What’s the best way to address this problem?

 

Notice, with each problem the customer realizes that it’s a problem; but the need that will be used to fix the problem has not been identified. Ultimately, all problems should be translatable to a definite need that everyone agrees on. Following is the updated Problems/Needs list with the problems translated to a need. (Note that with requirements it is good to keep all of the information in place and add notes as changes are made. Then as questions arise as to where the requirement came from, you have the historical data to refer to.)

Problem/Needs List UPDATED

1.1 NEED:  Need a dashboard that reflects current sales by region
1.2 NEED:  Add region data added to the database.  Need to get the CD from the Post Office that includes city, states and zip codes. Verify that the region data is also included. If not our DBAs will need to add the region data.  (Description for the need is: This need resolves 1.2 Problem:  Currently, end users are not able to associate a customer order with a region (data can only be associated with a city and state). Should we have the system assign the region based on the city/state? How can we fix this problem?)
1.3 NEED:   Need to be able to generate reports for segment marketing. We need to implement a business intelligence solution.
1.4 NEED:   Need a Customer Support Role. This role should be the only role with the right to add a customer order. No other roles should be granted this right. .  (Description for the need is: This need resolves 1.4 Problem: All employees can add order records, when only Customer Support should be able to add order records. What’s the best way to address this problem?)

 

Once the problems/needs list has been completed you will need to ask about the Features the system is to support. Features are the highest level of requirements.  The features will ultimately be used to organize the use cases.

Following is a list of features to provide an example of what a feature might look like:

 

Produce Features

 

1.     Manage Customer Records

2.     Interface with the XYZ Accounting System

3.     Generate Business Intelligence Reports

4.     Manage Sales Records

5.     Manage Employee Records

6.     Manage Customer Orders

 

Both the Problems/Needs list and the Product Features are added to the Vision document, which includes other information such as information about the stakeholders (individuals who are directly impacted by the success or failure of the projects). The Analyst should ask stakeholders whether or not they have any type of success criteria. A success criterion is a requirement that the system or project must meet for the project to be viewed as a success. For example, a success criterion may be that the system must be in place by a specific date. If this is the case adding a priority to your features, use cases and functional requirements become critical. When you have short timelines, you will need to work with the stakeholders to prioritize the requirements. Requirements marked with a “High” priority are implemented first. Then the “Medium” priority requirements are implemented once all “High” requirements have been successfully implemented. Lastly, your “Low” priority requirements are implemented once the Medium priority requirements have been implemented.  The following table shows an example of the High, Medium and Low priorities mapped to features, use cases and functional requirements.

 

 

Features	Feature Ranking = High	Feature Ranking = Medium	Feature Ranking = Low
Use Cases	All Use Cases = High priority	Approximately %50 of use cases = High priority – ONLY IMPLEMENT THE USE CASES MARKED AS HIGH.	Less than %50 of use Cases = High priority– ONLY IMPLEMENT THE USE CASES MARKED AS HIGH
Functional Requirements	All functional requirements = High priority	Approximately %50 of functional requirements = High priority– ONLY IMPLEMENT THE FUNCTIONAL REQUIREMENTS MARKED AS HIGH	Less than %50  of functional requirements = High priority– ONLY IMPLEMENT THE FUNCTIONAL REQUIREMENTS MARKED AS HIGH

 

 

In addition to adding information about the stakeholders, information about the end users of the system is also included in the Vision document. Other information included in the Vision document includes the technical documentation and end-user training requirements as well as a high-level list of other requirements such a performance. Once the features have been identified, the use cases are defined and added to the use case specification.  Then the functional requirements are defined and added to the software requirements specification.

To accurately design a business solution from requirements; the analyst must take on the role of a detective. He or she must search for unknowns; and, turn mysteries into concrete statements for feedback. At times the analyst will have to draw conclusions from provided information; and, clearly state those conclusions for feedback. Thorough investigative work is what it takes to accurately define a business solution. But it also takes an understanding of the technology associated with the project.

It's also good practice to gain an understanding of any initial groundwork already laid for the project. For example, ask for a copy of the Statement of Work (SOW). Also, ask for existing system documents, system diagrams, and access to the current system, if applicable. And, in some cases, personal time may need to be used to read through the materials--if the deadlines are tight. But, it is worth it to put forth the effort to gain this insight prior to meeting with the customer. This allows requirements gathering sessions to be used to gather requirements.

Summary
Below is a list of tips you may find useful while meeting with customers to understand system requirements:

1. Ask for existing system or project documentation.

2. Be willing to use your personal time to learn concepts if deadlines are tight.

3. When meeting with the customer ask questions. And, make sure the stated business problems/needs are addressed.

4. Enter all requirements into a requirements management system.

5. Perform a gap analysis between the current system, the business problems/needs and the use cases and functional requirements. If a business need has not been translated into an actionable requirements be sure to translate it to either a use case or functional requirements—based on the need and how it is to be implemented.

6. Write questions that will help close the identified gaps. Then be sure to obtain complete answers to those questions.

7. Update the requirements as you receive answers to your questions.

8. Generate a trace matrix or report for customers to review.