How We Do It

Technical Writing

Our Subject Knowledge

As experienced contractors, we are accustomed to starting work in new business environments. Many people think that a Technical Writer needs to have specific past experience in the type of equipment or system that is being documented, or previous knowledge of the subject matter. This is not so.

Early on in the technical writing process, we familiarise ourselves with your product and establish exactly how much we need to know about it in order to write the documents. We usually need to gain a broad overview of your product, so that we can ask the right questions to get precisely the information required for the documents.

This is our professional skill. We ask the right questions. Then we can produce the right documentation.

If you look at the Our Experience page, you will see that we have produced documentation for a wide range of business environments including:

  • Financial
  • Telecommunications
  • Health
  • Human Resources
  • Utilities
  • Education
  • Government
  • Military
  • Videoconferencing
  • Payment Systems
  • Document Capture
  • Foreign Exchange
  • Stage and Studio Lighting

We had no specific previous experience of any of these subjects before we started documenting them. Yet, we have a provable track record of producing the highest quality documentation in these subject areas for major international organisations.

As far as we are concerned, everything can be broken down into simple concepts. None of it is rocket science. In fact, we are even beginning to wonder how difficult rocket science really is....

The Documentation Process

Our approach to, and management of, any project varies according to the individual situation and requirements. The following example shows the stages that might be involved in producing manuals for a software development project.

Although different rules apply to the Agile environment, the standard documentation process is outlined in ISO/IEC 15910 Information technology—Software user documentation process as follows:

  • Determine the deliverables
  • Research the content
  • Write a documentation plan
  • Design the document structure/page layout
  • Write the first draft
  • Develop the graphics
  • Compile the text and graphics
  • Review the first draft for technical accuracy
  • Amend the draft and graphics
  • Incorporate the user comments
  • Edit the grammar
  • Prepare the second draft
  • Review the second draft
  • Make the final corrections
  • Test the documentation

In practice we would work through the stages outlined below.

Stage 1 - Documentation Requirements

We discuss your documentation requirements with you:

  • Assess the number and types of documents you will require. For example, will you require Installation Manuals, Administration Guides, User Handbooks, Quick Reference Guides?
  • Establish the target audience for each type of document. For example, will the software be installed by technical staff only, administrative staff only, the general public? The content and level of technical language of each document will depend on this.
  • Determine who the stakeholders and subject matter experts are.
  • Define the dictionary and style guide that the documentation is to conform to.
  • The planned delivery date of the completed software.
  • The planned delivery date of the documentation.
  • Your milestones. For example, when you expect to release development versions of the software, whether the testers may require drafts of the documentation.

Stage 2 - Information Gathering

We interview your stakeholders and subject matter experts (SMEs) to gain a broad understanding of the system under development. We would require copies of any relevant specifications, reports and other associated documents that would help us to gain an overview. If necessary, we would set up formal meetings at convenient times to minimise the disruption to your staff.

Stage 3 - Create a documentation plan

For a major project we would use Microsoft Project to establish the various milestones in the documentation process. This would be updated throughout the project to take account of changes in the project plans. It would be available to you and form the basis of our reports to you.

Stage 4 – Create Outline Documents

We write outlines of each of the documents. These usually contain no more than each of the main headings of the documents followed by a sentence or two describing the proposed content.

If required we would create document templates at this stage.

We would ask you to review these outlines to ensure that our interpretation of your requirements aligns with what you are expecting to get. This step avoids time and effort being wasted due to normal human differences in interpretation of the requirements.

Stage 5 - Writing the First Draft

This is usually the longest stage of the process. A great deal of care is taken to ensure that the documents:

  • Are written for the correct target audience
  • Contain enough information
  • Include relevant figures and tables
  • Do not contain irrelevant information
  • Do not contain any ambiguous statements
  • Flow logically
  • Are consistent between volumes
  • Use a consistent house style for typography, grammar and spelling

During this stage it may be necessary to get more information from stakeholders and SMEs. In the case of software with a user interface, we would need to get screen shots.

It is essential at this and every following stage that we are informed of changes that may effect the documentation.

Stage 6 - Review of the First Draft

At this stage we distribute controlled draft copies to the SMEs and stakeholders. There would be a deadline for the return of the marked up copies of the draft, as defined in the document plan. After the documents have been returned, it may be necessary to call a review meeting if the comments are unclear or conflicting.

Stage 7 - Writing the Second Draft

The second draft incorporates the review comments, including changes to graphics and final screen-shots. The whole document is tidied and edited for grammar, spelling and typographical errors. It is also checked against the appropriate style guide for consistency.

Stage 8 - Review of the Second Draft

Controlled draft copies are again distributed to the SMEs and stakeholders. As before, there would be a deadline for the return of the marked up copies of the draft. Again, a review meeting may be required.

Stage 9 - Writing the Final Draft

Any changes would be incorporated in the final draft. It would have a final edit session and be carefully checked for any typographical errors.

Stage 10 - User Testing

If required, an additional User Testing stage can be included, in accordance with ISO/IEC 15910.

Stage 11 - Sign-off

The stakeholders ensure that the documentation meets their needs and individually sign-off the documentation. The Project Leader then ensures that the documentation has satisfied its stated objectives and then signs-off the documentation.

Why Employ a Technical Writer?

Your product documentation can be a major marketing asset for promoting your business and your products. As well as ensuring that your customers get the most out of your product, high quality documentation can be used as source material and support for your marketing strategies. It also ensures that support staff spend less time on calls. However, poor quality documentation at best prevents your customers from making the most of your products' features and at worst frustrates and loses customers.

So how do you ensure that your documentation is of sufficiently high quality? There are basically two options for producing documentation:

  • You can employ a technical writer.
  • You can get the developers who developed the product to write the documentation.

Why not use the developers; after all, they understand the product best, don't they? There are a number of major disadvantages to this approach:

  • Good documentation takes a lot longer to write than most people anticipate. During this time one or more of your developers, important resources, are unavailable for their real jobs.
  • You employed your developers for their IT skills, because that is what they do best. If you had been interviewing them only for their writing, documenting and illustrating skills, would you still have employed them?
  • Developers may well understand the design and workings of the product but they do not necessarily understand how the customer will apply the functionality, or even what the level of technical understanding of the customer is.
  • They usually hate doing it!

The greatest 'crimes' that developers commit when writing documentation are:

  • Too much technical jargon. They forget that the reader does not understand their everyday technical terms.
  • Insufficient information on a subject. They assume that the reader knows as much as they do.
  • Too much information on a subject. They lose the reader by including information that the reader does not really need or want.
  • Ambiguity. It is easy to write sentences that can be misinterpreted.

Employing a Technical Writer has many advantages. Technical Writers are:

  • Highly experienced in all of the stages of the documentation life cycle
  • Experts in assessing the target audience for the documentation and the requirements of the reader
  • Experts in asking the right questions to get precisely the information required for the documents
  • Experts in describing complex concepts in a way that can be easily understood by the reader
  • Highly skilled in the most efficient use of documentation and graphics software
  • Experts in the use of English and able to ensure that no statements are ambiguous

We are experts in our field. You could employ us as developers – given enough time we would probably develop a software product that almost works. Maybe. After a fashion. It would be as efficient and cost effective as employing developers to write user manuals.

As professionals in our field, we can ensure:

  • The minimum disruption to your staff
  • That your delivery dates are met
  • That your documentation costs are controlled

Our documentation methodologies have been developed, tried and tested by us over many years. We can ensure that everything is managed efficiently and correctly so that you and your team can get on with your work.

Training

We offer custom-made professional training solutions in IT applications, Software and Business skills. Every client has diverse requirements, so we design training programs that are customised specifically to the way that you need to do business. We can develop end-to-end training programs or we can help you with any of the following specific areas in the training lifecycle.

The Training Lifecycle

Stage 1 - Analysis

At this stage we research and analyse your training needs. We prepare a report that covers questions such as:

  • What are the key business benefits for training?
  • Who are the trainees?
  • What do they need to know?
  • What do they already know?
  • When do they need to know it?

At every stage we prepare a draft for your review to ensure that we never lose sight of your requirements.

Stage 2 - Design

We design a training plan customised to the needs of your trainees. The plan usually includes the 'nuts and bolts' or framework of the training.

  • Method - What training method would best suit the needs? (e.g. Classroom - eLearning?)
  • Format - What format would best suit the needs? (e.g. Hands-on Training, Slide presentations?)
  • Presentation - What is the best way to present the information? Do you have existing standards and templates, or do we need to design some for you?
  • Accuracy Check - What is the best review or testing method to ensure accuracy of the training material. (e.g. Subject Matter Expert Review)
  • Schedule - What is the best use of the trainees' time? What is the best 'window' in the business for training?
  • Assessment - How will the trainee know if they are successful? How can the business assess if the training is useful and relevant?
  • Storage - how can the business access the training material now and in the future?

We prepare a draft of the training plan for your review and acceptance.

Stage 3 - Development

Our trainers begin preparing training material. This may involve access to software systems, machinery or specialist staff. It may involve written procedures, Captivate eLearning modules, PowerPoint slides or video modules. Whatever the format, the process includes:

  • Research the subject
  • Create the training material according to the agreed design
  • Create Assessment material according to the agreed design
  • Review. We send information to relevant business and subject matter experts (and other stakeholders) for a review of the content and standards, consistency and quality, relevance and accuracy.

We prepare as many drafts as needed to ensure that the material is relevant, accurate and meets your business standards.

Stage 4 - Delivery

We deliver training. This may be Face-to-Face presentation or shipment of eLearning modules. It may involve a blended learning solution where a number of training methods are delivered in stages. Whatever the method, we provide:

  • Professional Standards
  • Delivery to deadlines
  • Excellence and Quality

Stage 5 - Assessment/Evaluation

Assessment can be two-fold:

  • Trainee Assessment - How does the participant know if they have successfully acquired knowledge or skill?
  • Business Benefit - How does the business know if the training has been successful?

Not all training needs to be assessed in a formal manner.  We can design an assessment package suitable to your business, including assessment criteria, assessment tasks and assessment results.

Graphics

Visual aids, or graphics, are an integral part of our Technical Writing and Training solutions. We create visual elements (such as pictures, diagrams, and flowcharts) that illustrate and clarify the text. The graphics bring the information to life. They:

  • Are understood more quickly than words
  • Help readers retain information and learn
  • Communicate what words cannot
  • Entice readers and learners

Types of Graphics

Some examples of the types of visual aids we can create for you are:

  • Charts and Flow Charts - to represent parts of a whole, or relationships
  • Tables - to display and organise large amounts of data
  • Diagrams and Drawings - to show how something looks or works
  • Graphs - to show relationships and patterns over time
  • Maps and Process Diagrams - to show relationships between elements of a system or process
  • Photographs and Screen Shots - to show how something looks or works
  • Icons and logos - to use on Interfaces or design templates
  • Templates - to present page layouts and styles in a pleasing and professional manner.

Graphics Tools

We have extensive experience in a wide range of graphics software. We are up to date with modern trends, but can also create good visuals using traditional methods. Some of the more popular software programs we use are listed below.

  • Adobe PhotoShop
  • Adobe Illustrator
  • Adobe InDesign
  • Adobe FrameMaker
  • Adobe DreamWeaver
  • Adobe Captivate
  • Adobe Flash
  • Microsoft PowerPoint
  • Microsoft Visio
  • CorelDraw
  • PaintShop Pro
  • AutoCAD
  • Screen Capture software such as Snagit