# Technical writing/Edits

back to Technical Writing Level 1

## 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

## Read More

* Michael Knowles on Technical Writing
back to Technical Writing Level 1