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

1. How do we ensure that the Document is the latest version?
2. Why do we negotiate deadlines?
3. Why do we estimate man hours?
4. When do we define the scope of the document?
5. Why are you on this course?

• back to Technical Writing Level 1