Technical writing edits

From Wikiversity
Jump to navigation Jump to search
You work for your audience.

back to Technical Writing Level 1

Ego and the technical writer[edit]

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[edit]

  • 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[edit]

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

Design[edit]

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

Develop[edit]

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[edit]

  • 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[edit]

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

Information[edit]

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[edit]

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[edit]

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

Test Tracking[edit]

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[edit]

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[edit]

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[edit]

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[edit]

back to Technical Writing Level 1