Alice, the Technical Writer, Meets the White Rabbit

The mission of the Technical and Document Writer is to ensure all the details required by the readers/ users of the documents are presented in an accurate, clear, 'Plain English' and actionable way.  This means creating a simple, consistent and frictionless presentation of ‘the organisation's truth’ in the required format and style. 

Creation

Ideally, if a workflow process has been workshopped thoroughly and is formally approved/ signed off, it forms the best foundation for the technical writer to write a work instruction, procedure, how-to guide, etc., because it should be accurate and stable; and provides the purest and quickest way to complete a document. 

Once complete, the initial review by SMEs should uncover whatever is missing.  This can be more easily added and/ or embellished, as needed, once all facts are included in the structure.

Supplementary Documents

If there are supplementary documents, such as communication templates (internal and/ or external), I tend to suggest them as I am writing the work instruction, as they flow naturally out of the document. 

Reports, such as summary sheets, or special documents such as Statements of Word (SoW) and Notice of Determination (NoD), might also need to be included in the workflow -- as well as any legally-required communication that would not be apparent from the workflow. 

Screen shots

Sometimes these are suggested from the activities, such as ‘receipting’ an application or transaction.  These screen shots are easily produced directly from systems that will typically be used in completing the tasks.  

However, there are screen shots that only appear when an action is further developed (such as printing an Excel report from the details collected).  These might be best sourced from someone who has the proper authority to access the systems.  

Review

To help make the work easier, effective and efficient for the technical/ document writer, here are six points to keep in mind if you are asked to review and comment on a document.

     1.      Moving or adding chunks of text

Primarily this is about cutting and pasting bits of copy from one document into the ultimate document and often this changes pagination and introduces embedded codes or additional structures.  If you need to do this, just highlight it so it is easier to find and ensure it is blended into the document.

     2.     Moving illustrations

Many of the illustrations have layers of communication within them and when moved, such as right justifying them, pointers and ‘attached’ highlights may not move with them.

     3.     Adding extra lines

    The number of lines between sections is strictly established and when, for example, a segment of writing is separated from a heading when it moves to the next page, adding a number of lines before the heading means these will have to be removed when the document is finalised.  Leave this work for the Document Manager.

     5.     Changing case randomly or capitalising words just because they are nouns

    I'm unsure where this started, but it is a common error that is made when a word like 'technical' is capitalised:  Technical, perhaps to add emphasis or strength to the word.  It is also used when referring to a human resource designation such as manager to Manager.  

     Typically, this type of adjustment is rarely made consistently within the document, and is incorrect.  

     6.   Using words consistently throughout the documents, such as flood works or floodworks, assessments or evaluations, etc.

     7.     Changing/ adding heading structure  

    Heading structure is set within the template of each type of document for consistency, not style preference.  Changing or adding a level to the structure only means the Document Manager will need to readjust the headings before publishing a document.  Adding work and time to the task.