Technical writing Collaborating EE
- back to Technical Writing Level 1
Collaborating
Before more than one person can work on a document everyone must be sure which copy of the document they are working on. It is very easy to start working on an outdated copy and this will duplicate work and sometimes create multiple parallel copies none of which contain all the necessary information. Most companies use a form of versioning or document control. This can be as simple as serially emailing the document so that one author has control of the document at a time or by using a versioning system that only allows certain people to book out the document one at a time. Increasingly companies use:
- Content Management Systems (CMS) so that different sections of the document can
be edited at the same time
- tasking and tracking programs which link the document to a software release
Which Version of the Document is the latest?
If the technical writer cannot validate which document is the latest version then the technical writer cannot give the reader the correct information. If the version is old then the reader can cause damage to the product. If there are several versions of the product or software the problem of identifying the latest version multiplies exponentially.
Tracking versions of documents with a CMS or Versioning system
If more than one person works on a document (including validation or editing) use a Versioning system to track the version of the document. Examples are:
- Open source Wiki based content management systems
- Wiki Media
- Confluence
- DocBook
(All the above automatically number each version of each section each time they are edited)
- Madcap Flare
- FrameMaker
- RoboHelp
Most Software tracking and tasking systems can be adapted to track the relevant documents for example: ● TFS
Tracking versions of documents without a Content Management system (CMS)
The reader needs the latest version of the document. If more than one person work on a document use a Versioning system to track the version of the document. Examples are:
- accepted rules for naming, numbering and archiving documents including the:
- software version
- service-pack or patch
- date and time
- Wiki based content management systems
- WikiMedia
- Confluence
- Madcap Flare
Then Technical writer and SME must work on the latest version of the document.
Collaborating on a document
Where more than one person works on a document (for example in large companies) one person must be responsible for:
- the delivery of the document by the deadline
- the inclusion of all content
- communication with all SMEs
- the completion of the document
- the format of the document
- securely archiving the document
Planning the document
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.
Estimate the extent of the work
How many man hours will it take to complete the work? Add 50% for contingency
Negotiate and define the deadline
When is the document needed by? Agree deadlines and procedures to keep the work on time.
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.
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.
Development
Once the work has been fully planned we now instigate the following steps:
Planning the tests
- 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
Test Cases
When a test documented, this is known as a test case and has three parts.
- 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
- 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 fulfils 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.
Write for your reader.
- Use simple language.
- Use your reader's vocabulary.
- Use diagrams and pictures
- Use the Systems Development Life Cycle.
- Explain things in a way the reader will understand.
- Provide accurate and precise information to your reader.
- Correct the Document
- Get some one else to check and validate the information and formatting
- Nothing you write belongs to you.
- If the information is not useful to the reader, 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"
End of lesson Test
- How do we ensure that the Document is the latest version?
- Why do we negotiate deadlines?
- Why do we estimate man hours?
- When do we define the scope of the document?
- Why are you on this course?
- back to Technical Writing Level 1