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.

Good – Fast – Cheap (Pick two)

I was recently asked by the Society of Technical Communicators to write about customer service, just thinking about the level of customer service I find today, the number angles and topics that came to mind was overwhelming.  Considering you as the audience, it seemed important to focus on what might serve writers and how customer service is critical for our craft.

Service is basically common courtesy and common sense – providing the service we would like to have provided to us.  As writers this means we deliver what we promise for the price we quote, in the time agreed --the ultimate in customer service.  Most of all, we keep our readers and the one who is paying us in mind throughout our work.

You want what by when for how much!

Whether writing a novel or a complicated explanation of an intricate IT network process, a work instruction or test case -- the perception is that it cannot be that difficult to write, write quickly and for almost no cost! 

The reason is simple -- people have been writing since grade school.  However, this complicates our work when it comes to charging others for what they believe they could do themselves if they just had more time.

In the 80s the mantra of business was: 

·       customers come first, shareholders next and profits last.

By the ‘90s there was a shift to:

·       shareholders first, profits and customers last

Today, it is typically:

·       profits first, shareholders next and … well customers are just too expensive to serve anymore. 

As writers this current shift means the major driver for our work can be to get the most for the least cost. 

Quality is not always as important as cheap and fast.  Yet, cheap and fast does not deliver quality that is necessary for repeat business and to provide good customer service.  It just gets through work quickly, results in heaps of rework and the writer suffers from lack of income when the client is not happy.

Define the work carefully

In my experience, success begins with defining and measuring what needs to be done.  Then establishing a schedule to meet the client expectations.  Here is a different, yet critical type of writing.  Start with precisely defining and documenting what is to be delivered, by when and for how much. 

This can often seem like ‘nailing jelly to the wall’, yet the effort will pay dividends with your reputation and repeat business.  It means you can know when you meet your customer’s expectation and deliver good service. 

Ensure there is no ‘wiggle room’ to misunderstand what is being agreed to and your client will be an excellent reference for you in the future.

Scope creep

The enemy of every project -- no matter how large or small -- is agreeing to the scope of work within a set schedule and the client asking for changes or ‘just one more little thing’. 

Scope creep is especially poisonous for writers because we sometimes are so grateful for the work, we just want to get to it rather than formalise things.  The inclusion of change orders and how they may impact the cost and time upfront is critical.

Make it clear you intend to deliver the best quality for the defined scope at a fair price in an agreed-to timeframe.  Any required changes must be defined, costed and agreed to before they can be undertaken.  Changes can impact the delivery date, or the work may need to be delivered in stages. 

Writing and managing change orders can become more time consuming than the original project and if they grow too ponderous it is time to have a good talk with the client.  Everyone must understand the rules of the project before it begins, to manage potential complaints later.

Time

Professional writers know that to write well, to be thorough and accurate, is not about the time spent writing, it is the time preparing, researching, thinking through what is needed, what is meant, what the reader needs to know, writing for the reader, editing and proof-reading. 

There is legal, compliance or audit requirements that often must be met, especially by technical writers.  Clients want to know why it is taking you so long.  Pricing your writing to meet deadlines is a huge challenge.  It is the measure twice, cut once rule that will ensure you are profitable and popular.

Cheap

Pricing success comes from pricing fairly.  Most of us do not make $100 per hour writing.  Endeavour to set your fees, not on what others charge, but for how complicated the topic, the level of the audience/ reader, your overhead, the time the client is allowing to complete the work … you will know the key factors to include.  Never be afraid to turn work down because if you do not, it will come back to bite you.

If you have been in or near organisational customer service, you know the ‘holy grail’ is -- and always will be -- how can we put a price on the cost of adding customer service on top of what is delivered? 

When I was a child, if you found one gasoline service station at an intersection, there would be three more, one on each of the other corners.  You choose by the personally perceived brand value and the customer service received.

One day we pulled into our favourite Texaco station.  The service attendant took my Dad’s order to ‘Fill-er up’ and popped the hood to check the oil and water.  I noticed the cost of a gallon of gas was less at the Mobile station across the street.  Over the months that followed, a gas war took place and gas stations began to close as competitors sacrificed profit to undercut their rivals.

It might have been alright if it has just stayed with gasoline stations, but the idea of undercutting your competitors with the hope of being the last one standing lingers today.  Resist the temptation.  Price fairly and your customers will come back for more. 

Conclusion

Extraordinary customer service in writing comes from having as much information about the expectations of the client as you can.  Being honourable and truthful about your ability, experience and availability to meet the requirements.  Always

·       Define the work precisely

·       Price fairly

·       Work to an agreed schedule

·       Ruthlessly police scope creep

·       Deliver what you promise

Being professional means, you clearly establish and mutually agree in writing on what will be delivered, at what price, by when and the impact of scope creep.  If you do this and you fulfil your agreement, there is no better customer service!

Artistry in Technical Writing

The Extraordinary Artistry of

Technical Writing

 

When you modify “writing” with an adjective like “technical” it seems an unlikely combination.  Yet, they fit together in a magical way, only we who have practiced this craft for a while understand.  Those new to the art struggle to grasp the artistry angle because it is not found in any off-the-shelf training course.

Motivating purpose

Knowing the motive underlying the writing helps.  It is always important to state it clearly and get agreement before you begin.  Without the purpose you are just writing in circles.

For example, if you are writing to remediate behavioural errors or to encourage a new way of working, there are different ways to approach the body of work.  If you are writing to substantiate auditable process or test some new ideas, the motive of your task will also set the tone and your approach.

Audience

One of the most valuable lessons shared with me was to write to only one person at a time, to see that person and appreciate their position in reading what you are writing. 

You can do this by asking others about those who will utilise your work or best of all, you can take time to meet with several of them, if time allows.  Listen carefully as they share how they manage new instruction, whether they are fatigued with too much change or unaware of the need and motive for new documents.

Time

Time is always a difficult challenge.  Everyone is in a rush nowadays.  Although technical writing cannot be likened to painting the Sistine Chapel, it does take more time in combining the “soft” information (motive, audience, feedback, etc.) with the edgy reality of accurate and concise information. 

Yet, it takes time to change, so you must take time to ensure there is no “friction” in what you write.  If you do not it easily can provide reasons and excuses to resist embracing the new way of understanding something familiar. 

NOTE:  Friction is anything that might slow down or stop your reader.  Friction includes making something too complicated, convoluted, or wordy.  Not checking for accuracy and sensibility of the process (see “A Secret” below), misspellings, using acronyms or words that no one is sure of.

Parameters and constraints

Every organisation requires you to respect their parameters of style and tradition.  There are always template constraints (even those you create) and editorial/ brand standards to be met.  Be sure you are a shining example of doing this with consistency. 

Remember, creativity is at its best when you learn how to work within set guidelines and maddening constraints to maximum effect.

Collaborators

Seeking the best subject matter experts is obviously important.  Yet sometimes this can be one of the greatest challenges you face.  Many subject matter experts are selected for you.  Many have at least half-dozen reasons to resist your probing for the truth, including fear they will be too easy to replace. 

Being able to “charm” reluctant individuals with the motivating purpose and benefits of having new documents will demonstrate your strength in creativity.

Mentors

Anyone who writes alone is foolish (that is my opinion, and I’m sticking to it because it has proven me right too many times).  We all find a bit of sensitivity crops up in our hearts as we write.  Having someone to bounce ideas off, who will read your work with care and candour (before it is released to the wider audience) will serve you a million times over.

The Secret

Technical writers who are also “closet” analysts, have a secret.  It gives them a significant, advantage when writing any type of document.  Why?  Because they know how to unravel the fine threads of any process, procedure or written information.  They can follow the reasoning and logic through with child-like innocence -- and correct it where necessary for the benefit of the ultimate reader.

How to manage technical writing projects remotely

I was asked to address how to collaborate on technical writing projects remotely.  Here is what I’ve found works well.  We have a virtual team of seven and a huge body of work for a government utility.  The work includes analysing and defining processes and writing: 

Processes	Procedures	How-to/ user guides
Special reports	Training aids	Work instructions
Glossary of terms and acronyms	An overall manual	Wiki of all information

The Methodology

Here is a high-level overview of how we manage our workload.  I hope this provides some helpful ideas:

Meetings

We meet at the start of every new project to

1.      discuss project structure and participants (for example:  subject matter experts (SMEs), those who will be required to review and sign off the documents.

2.      sign off rules to handle the details of how we will work to create and distribute documents.

We set two recuring weekly meetings.  Everyone involved with the documents (including representatives from the subject matter teams) is required to attend: 

·        one on Monday mornings (discussing plans for the week, any constraints, challenges or conflicts)

·        the other on Friday mornings (review and celebration of the week’s progress – usually with everyone having virtual coffee/ tea and cake).

Tools

1.      Our tools of collaboration are Microsoft™ Teams and SharePoint.

2.      In SharePoint we set up sites and folders according to rules all agree to, this includes an:

·        'In development' folder in SharePoint that is only accessible by those writing documents – it includes agreed to sub folders by topics

·        'In production' folder in SharePoint where finished, to be reviewed and signed off documents are stored in PDF-only format, accessible to users – with structured sub-folders by topic.

3.      We use a consistent and easy-to-understand language for labelling folders to make it easy for staff to locate documents.

4.      No other documents are stored in the collaboration sites but work in progress.

5.      We establish a structure that relies on one version being stored in SharePoint and use document history should previous versions be required.

Document Manager

We charge one person to be the document manager.  They have the responsibility to

1.      audit and maintain the document rules.

2.      manage permissions, structure and any problems with the SharePoint sites

3.      monitor progress of all documents, for group reporting.

4.      maintain the list of unfinished or incorrect information and return documents to the analyst to correct/ complete.

5.      to do a final 'polish' of all documents along their journeys to ‘tie up any loose threads’ and make decisions about content, structure, format, etc. to result in a ‘consistent quality’ of the product.

6.      PDF all final documents before they are removed from the development site and moved to the production site.

7.      pull all manual segment documents into the structure of the ultimate manual and wiki once a document segment is completed and signed off.

Document Rules

1.      We established templates for each type of document that all must agree to and use.

2.      We maintain a strict naming convention for files, folders and documents.

3.      We maintain a team Microsoft™ OneNote that includes

a.      a tab for each contributor for their ongoing discoveries, questions and segments of frequently used copy

b.     an ultimate progress list with the analyst writers responsible for keeping their progress deadlines current

c.       a shared list of tasks and who is responsible for what and by when

4.      When a document is being reviewed by an SME on an uncontrolled document, we provide the reviewer with clear instructions for how we require changes to be noted.  (For example, we ask the reviewer to use ‘Comments’ in the ‘Review’ section of Word, and not ‘Track Changes’)

5.      We instruct reviewers not to worry about spelling or formatting -- as this is all pulled to one consistent standard by the document manager.

Analysts Writers

1.      In our team, there are three process analysts who work with subject matter experts (SME) and collaboratively create process flow documents with them.

2.      After the process flows are developed, they are sent to the document manager to review.

3.      The document manager uses ‘fresh eyes’ to review the ‘as is’ and ‘to be’ approaches for logic and potential improvements

4.       The process analyst is responsible to store only ONE version of a document in the collaborative SharePoint (which can be accessed by other analysts -- who may make or be asked to make -- contributions)

5.      All documents hold a warning in the footer, ‘If downloaded, this document is an ‘uncontrolled copy’. 

6.      Copies of uncontrolled documents must be approved for release by the document manager if required.

Conclusion

Although this exact type of structure may not work for every project, it should give some hints at the many things to consider when working collaboratively and remotely. 

One thing I have learned is that if the management of the work becomes too complicated, or scattered in the hands of too many, it is doomed to be resisted and will fail.  I think the K.I.S.S. formula works best in all things. 

How to Use Track Changes in Word

Track Changes is an easy way to collaborate on documents and indicate required improvements and edits in a Microsoft™ Word document.  Here's how to use it:

1. Open (or have open) the document you are editing

2. Make a copy of it and put your initials at the end (file away the original)

Example:

Document name = 'How to use track changes 1'

New name = 'How to use track changes 1 - MHC' and save the document.

3. To save the document, open 'File' at the top left corner on the ribbon at the top of your screen and choose:  'Save a Copy' with the new name.

4. Resist adjusting the original document, in case you need to refer back to it.

Now you have a copy you can easily edit.

5. While in the new version, on the ribbon above, locate 'Review' and click it:

This is the new ribbon that will come up:

7. Click on the down carrow next to 'Changes of 'Track Changes'

8. A drop-down menu appears.

9. Click 'Track Changes' to turn Track Changes on and off.

10. Once activated, any change you make will be indicated in red.

Example:

Words you chose to eliminate will show a red line through them.  This way it is easy to see what you have changed, and a vertical line appears on the left side of the document, so the changes can be found easily by someone else.  (Yes, it looks messy, but just keep going).

11.  Whatever changes you make while ‘Track Changes’ will be recorded in red. 

12.  If you wish to see the edited copy without your red edits, click on the drop-down menu beside ‘Track Changes’ and change it from seeing ‘All Markup’ to ‘No Markup’

13.  Your copy will show how the edited version will appear with no markups.

14.  Track Changes will remain off until you turn it on again.

If you then wish to continue editing the document or revisit the edits:

15.  Click on the drop-down menu beside ‘Track Changes’ and select ‘All Markup’.

Adding comments

There are times when you may have a question, observation, suggestion that you would like to add.  This can be done, also in ‘Review’ by using the comments facility.  Here’s how:

1.      Open the ‘Review’ ribbon.

2.      Have your cursor in the document, on the word or paragraph or illustration that you would like to comment on.

3.      Click on ‘New Comment’

This will change the margins of the document and open a column to the right where a comment ‘bubble’ will appear.

4.      Write your comments/ thoughts/ observations in the comment bubble.

5.      Another person can respond to your comments or ‘Resolve’ the comment (The comment will turn gray, so it won’t need to be reviewed again).

To delete the comment

1. Right click inside the comment box and select 'delete comment'.