Technical writing/Edits
back to Technical Writing Level 1
Ego and the technical writer
[edit | edit source]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 | edit source]- 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 | edit source]- 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 | edit source]- Blueprint - we now create the actual structure of the document we are preparing, how it works.
- Interface - how will the document look?
Develop
[edit | edit source]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 | edit source]- 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 | edit source]When a test is formally written up, this is known as a test case and has three parts.
Information
[edit | edit source]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 | edit source]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 | edit source]- Expected results - what should happen
- Actual results - what really happened
Test Tracking
[edit | edit source]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 | edit source]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 | edit source]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 | edit source]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 | edit source]back to Technical Writing Level 1