Technical writing edits
From Wikiversity
back to Technical Writing Level 1
[edit] Ego and the technical writer
Write for your audience. This isn't the place to use fancy language, or show off your vocabulary. Your job is to use your audience's vocabulary and explain things in a manner they will understand..
As a technical writer you must provide accurate and precise information to your audience. So your diction and style ought to be open to correction. You can always spruce up your writing and avoid errors with the help of your co-workers.
You write to help people do their job---You are a conduit not a fountain, you take information from the SMEs, provide it to the audience and then let it go. Nothing you write is "precious". If it's not useful to the audience, delete it.
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"
While preparing our writing it's best to use a pre-defined work flow. As we are working primarily with developers, it is useful to mirror the Systems Development Life Cycle.
Contents |
[edit] Planning the document
[edit] Define the type of a document
Decide on the type of format of the document. Often companies have a global template and style guides to follow. For example: Is the document a user manual? The type of information will be very different to an administration guide.
[edit] Estimate the extent of the work
How many man hours will it take to complete the work? Add 50% for contingency
[edit] Negotiate and define the deadline
When is the document needed by? Agree deadlines and procedures to keep the work on time.
[edit] What is the Scope of the document?
Decide what information will be included in the document and what information must be excluded for commercial reasons. Include the software release and any patch or service pack number.
[edit] Develop the structure of the document
Draft a list of chapters or section headings to be included in the document. Make a detailed plan of SMEs that will contribute to the document.
[edit] Development
Once the work has been fully planned we now instigate the following steps:
[edit] Analysis
- Persona needs — How will the text meet the needs of their persona? We cannot answer this question without being aware of those needs.
[edit] Design
- Blueprint - we now create the actual structure of the document we are preparing, how it works.
- Interface - how will the document look?
[edit] Development
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.
[edit] Testing
- Validate - make sure that the text is accurate and that the persona is happy with the text prepared.
- Refine - make any necessary amendments and improvements to the text or the structure, to meet more closely the needs of the persona
- Validate - test the refined text before moving on to the next stage
[edit] 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".
[edit] 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.
[edit] Planning
- Scope of the tests - what is to be tested and how?
- Test schedule - when are the tests due to take place and how long will they last?
- Pass/Fail criteria
[edit] Test Cases
When a test is formally written up, this is known as a test case and has three parts.
[edit] Information
This section contains general information about the test, such as:
- Identifier - each text 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
[edit] 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
[edit] Results
- Expected results - what should happen
- Actual results - what really happened
[edit] 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.
[edit] Read More
back to Technical Writing Level 1
