Technical Writing Edits

Ego and the technical writer

Technical writing relies on delivering accurate and precise information. Commonly, management and designated subject matter experts review all work performed prior to a documentation release. It is important to understand that a documentation review is not personal; diction and style is always a point of critique.

The famous English actor and scriptwriter Michael Knowles once said:

"Leave your ego at the door. Big egos cause big problems. Give me one good, persistent writer with a small ego and the two of us will do the work of ten"

Planning

• Define — exactly what are we writing? At this point we must decide on the format of our work.
• Scope — at this point we decide the parameters within which we will prepare our writing, always being mindful of the persona.
• Developing the plan — a detailed break down of how the writing plan will be executed.
• Monitoring — setting procedures to keep the work flow on track.

Analysis

• Persona needs — How will the text meet the needs of their persona? We cannot answer this question without being aware of those needs.

Design

• Blueprint - we now create the actual structure of the document we are preparing, how it works.
• Interface - how will the document look?

Develop

Once the work has been fully planned we now instigate the following steps:

• Research - find the information to be presented in the document.
• Writing - create the text that will form the body of the work.

Test

• Scope of the tests - what is to be tested and how?
• Pass/Fail criteria
• Test schedule - when are the tests due to take place and how long will they last?
• Validate - test the refined text before moving on to the next stage
• Refine - make any necessary amendments and improvements to the text or the structure, to meet more closely the needs of the persona

Test Cases

When a test is formally written up, this is known as a test case and has three parts.

Information

This section contains general information about the test, such as:

• Identifier - each test case has a unique number or code for ease of tracking
• Tester - the person who created the test
• Name - a test should have a human-friendly title for easy recollection
• Purpose - a brief description of what the test expects to do

Activity

This describes the actual test in the following terms:

• Environment — the conditions under which the test took place
• Initialisation — tasks undertaken before the test begins
• Finalisation — tasks undertaken once the test is completed
• Actions — a step-by-step guide to the test

Results

• Expected results - what should happen
• Actual results - what really happened

Test Tracking

Testing needs to ensure that the document fulfills the stated requirements of the project. When the requirements are established, each requirement must have a stated test. It is necessary that each requirement be testable, otherwise the requirement is pointless.

Implementation

The text is prepared and has been thoroughly tested, now is the time to create the documentation.

• Publish - whether in paper form, online or as a CD-ROM, this is the phase in which the completed text becomes "live".

Maintenance

Although the main body of the text is complete, updates are inevitable. Feedback from actual users will also form part of the process for implementing changes.

• Testing a document is an important quality assurance tool.

Training

Documentation development begins during the Planning stage of SDLC. When you write for development you write and participate as a team member in all aspects of development content. Developing process documents, proofing requirements, design, and technical specifications; and writing training documentation can be a part of your role.

Types of documentation delivery expectations for this stage:

Check list

• Requirements Document
• Design Document
• Technical Specifications
• Test Plans and Scenarios
• Implementation Plan
• Maintenance Plan
• Training Specifications
• Training Documentation
• Support Documentation