Technical Writing | Sourcing a technical writer

When sourcing a technical author, ensure their experience matches your requirements. You need to source one who has the right knowledge, background and expertise. At the interview, they should talk through that experience; if not keep searching until you do.

Productive years as a Technical Writer

An experienced Technical writer can only be an asset to your team or project. The longer their tenure, the broader and more in-depth their experience will be. However, the only way to be confident is to read their CVs carefully.

Do they use Social Media or have a website?

Check out LinkedIn for their profile; If you cannot find one or a website describing their experiences, what have they be doing?

During the interview, did they communicate?

During an interview be wary of a candidate who sits, listens, and says very little. An experienced TW will respond to your questions and may offer suggestions on how to elevate the project with innovations you may not have considered.

Read the CV and be prepared to discuss the project. I have arrived at an interview to find the interviewer has not read my CV. I have a simple rule regarding my experience; if you cannot see it on the CV, then I have not done it. That does not mean that I will turn down unfamiliar tasks.

Effective communication

An essential part of our job is the ability to communicate with SMEs to gather the right level of detail for the documentation. If the documentation appears vague, it might be time for a chat.

Do you want a contractor or permanent TW?

You may build a team, and you need a Technical Writer to keep the documentation up to date; a person who will grow into the environment. However, I would caution against using a Technical Writer permanently unless you are sure there will be ongoing work.

Work cycles can dip, so be careful how you use the Technical Writer.  During one of my earliest contracts, the project engineer referred to me as a secretary and treated me as one as did the rest of the team. In a much earlier role, my line manager used me to shift boxes and to clean the stock room and a general dogsbody.

A proactive Technical Writer between writing, researching and interviewing could improve the company’s documentation. However, once they get on top of the tasks, the role could become routine and repetitive. There will be the odd spurt of activity within the working life cycle; hence, why the position of Technical Writing lends itself more so to contract work rather than permanent work.

To summarise: if you use a permanent Technical Writer ensure you have plenty of contingencies within their job. To avoid your TW developing itchy feet, I would suggest that you discuss additional tasks that may add value to their experience. Allowing a member of staff use them for jobs, which an office junior should cover will not go down too well.

A word of caution

Unfortunately, our profession can attract its fair share of triers. You can reasonably expect CVs from candidates who have had minimum experience preparing ad hoc documentation. Unfortunately, that minimal experience will NOT be enough to perform the job.

Many recruiting agents have a minimum expertise sourcing Technical Writers. When they speak to prospective candidates, they hear a few buzzwords and place candidates forward for a role for which they are not suitable. Be sure to check that they have the right experience and background.

Applying the following advice may help you avoid problems:

Be careful hiring a Junior Technical Writer or one that has worked in a permanent position for the last five years.

Why: a permanent position can be very repetitive, which means the Technical Writer’s experience may be severely limited. That also goes for junior writers, for high-profile projects hire a seasoned contracting professional, who can talk through the project with you. In my experience, there is a world of difference between a contract Technical Writer and one who has chosen permanency.

Finally, budgets – ensure you are buying the experience you need. In the world of Technical Writing, the price you pay determines the standard you buy. By using the wrong candidate could be a costly mistake.

Where else can you source a Technical writer?

If you prefer to source a Technical Writer, you have found me. However, I may not be suitable for the role. Check LinkedIn, Social Media sites and the online Job Boards. Ask other companies and fellow professionals if they have used Technical Writers and if so, what was their experience. They may have recommendations which in the long run could save you money.

Technical Writing | The risks of poor document management

The risks of poor document management stem from managing multiple types of documents in different formats, workflows and updates. If the documents, which are in constant use have no defined structure it will lead to an uncontrolled and unmanaged repository. This haphazard approach to managing the document Lifecycle impedes employee productivity.

The scenario is this: you are sitting at your desk when your boss requests the latest version of a critical policy document. When do want it you ask?

The risks of poor document management
The risks of poor document management

Now is the reply as she has an urgent meeting. It is located on the company’s shared drive. Your search starts with your department folder.  However, it is not there. You decide to perform a search and type in the title. Your face falls flat when the search returns 100s of potential matches. You open up the most likely and find they are not current.  Panic sets in and your boss is now calling your desk phone, as she is late for her meeting.

We have all been there, as intuitively as we think we have organized our company “shared” network folders, documents get lost and frustration sets in. Whether it is neglecting to archive or delete the outdated version of documents, images, files, assets, etc. or employees using confusing naming scheme for the folder structure – the point is this archaic means of organising and managing documents/assets isn’t working for your company and it is costing you.

Failure to treat business documents as vital assets can lead to:

  • Diminished document utility
  • Decreased business efficiency
  • Increased operational risk and cost

Effective Lifecycle management

The management of Documents continues throughout their useful lifespans ensuring businesses meet compliance and regulatory requirements while preserving the productivity of employees and agility of business processes:

  • Quick access
  • Frequent review and updating
  • Distribution
  • Conversion
  • Archiving

Document management

The risks of poor document management
The risks of poor document management

If your document library is growing with no control consider creating a Document Management library to store and manage your documentation.

The growing influence of ISO and ITIL requires documentation to contain elements which relate to its History, Versioning and sign off, all of which are easy to incorporate. Going forward your staff should know how to manage the documentation in the absence of someone dedicated to the role.

Technical Writing | Disaster Recovery Plan

Document the Disaster Recovery Plan

Remember, to be effective you must be prepared to document the plan. Without the documentation you risk the possibility of NOT recovering from a disaster, therefore placing the entire company at risk.

If you have no existing documentation that describes the functions of the company’s servers and their hosted Applications, consider writing relevant Operating Document. In the event of a disaster, without knowing the role and the purpose of a server, as well as the Operating system – it could delay recovery.

A list of your critical systems

All companies will have a set of applications hosted on servers, which, are crucial to the business such as financials.

List your servers by priority and the criticality of the hosted Application – that is the amount of time the server and its applications can remain non-functional before it severely disrupts operations.

Create a disaster recovery plan for each critical system

This returns to the Operating document. To recover the system during a Disaster could take time, more so if the Owner is not available during the disaster to help login and failover the system then failback the system.

Therefore Keep documents simple, direct and to the point and written in such a way that anyone can understand the process, not just the SMEs who designed and built the system.

Who is responsible
Delegated participants must know and understand their responsibility should a disaster happen. Engage them in areas where they will know what to do and act accordingly. When compiling such lists make sure there are Team Leads, and Deputies should the first choice not be available during a disaster.

Make Backups
In this context be sure that if you use allocated drive space that your staff are backing up valuable information and documents to that allocated space.

Do you have an Off-site backup
Store all data in an Off-site Common.

Store Backups off-site in a location away from the same grid as the originals.

Test the Plan
On completion of the written plan, you enter the test phase. Make a plan to failover your infrastructure and then failback the infrastructure.

Take notes along the way to strengthen the areas in the plan which need more validation. Note where there is a need to access backup data time how quickly it takes to restore the system.

Keep the plan safe
Store a paper copy of the plan in a safe place. Remember: during a Failover, the online version could be unavailable.

When it comes to planning your Disaster Recovery strategy, do not forget the disaster recovery documentation. It may be the last project on your mind but could prove to be your company’s one lifesaver.

Disaster Recovery never stops and undergoes modifications every six months or twelve months.

Technical Writing | Technical documentation vs Helpdesk

technical documentation vs helpdesk
technical documentation vs helpdesk

Technical Documentation vs Helpdesk – Despite the reluctance to invest in technical documentation, many managers bypass a proven way to cut back on calls to the Helpdesk. No doubt many helpdesks provide an excellent service and manage the demands of the users. The problem with most technical documentation including user guides is that it is incomplete and full of gaps. Documentation needs to flow and provide practical tips on how to get the best from the software.  If your customers had well written and comprehensive documentation you could substantially cut back on costly calls to your helpdesk.

Technical documentation vs Helpdesk

technical documentation vs helpdesk
technical documentation vs helpdesk

I have experience in manning a premium line Helpdesk and have spoken to many angry customers whose subjective complaints about the company and the guilty software lead to comments such as:

  • The product is bordering on rubbish, and it doesn’t work, is it bugged?
  • annoyed with the company because the software is garbage
  • I can’t follow the user guide because it doesn’t belong to my version of the software
  • I can’t follow the instructions

When documentation fails to deliver the answer, the Helpdesk records a steep curve in calls. Customers who feel forced to call the Helpdesk Support can hold mixed feelings about the product and company.

Frequently Asked Questions (FAQs)

technical documentation vs helpdesk
technical documentation vs helpdesk

Customers are the lifeblood of any organisation, and their demands can vary.  To facilitate their requirements, I created a feedback option to enable internal and external users to point out where the documentation appeared vague.

The developers and helpdesk provided a more detailed solution based on their knowledge and experiences. I created a FAQs knowledge base (or Wiki) for external users and placed the information in the back of the document. The internal staff received the content via a RoboHelp *.chm file.

The FAQs were a success and helped cut calls to support by 80%. I had created searchable information that was easy to find and accessible to all staff.

Experienced technical writers can produce audience focussed documentation that helps customers maintain productivity.

Technical documentation vs Helpdesk

Always treat your documentation and your information as an asset’ and invest in the necessary resources maintain the documentation. The savings could be significant meaning satisfied customers.

Technical Writing | What is technical writing and why you need it

What is Technical Writing?

Technical writing is a skill and should you hear a Project Manager or Subject Matter Expert say: ‘anyone can write so “why do you need a Technical Writer?” continue reading.

Technical Writing like many jobs has many facets. The fact you see Writer in the job title suggests to the uninitiated that primarily we write. You could not be more wrong! The writing takes only a fraction of the time allocated to the project.

Let’s get to the point

Our time is taken with analysing content and listening to Subject Matter Experts.

Our Writing is concise and to the point. We are not novelists describing a beautiful character down to her laughter lines. A poorly written novel will not hold the attention of a reader; the same goes for poorly written technical documentation. A user wants to read the document and understand say – the function of multiple servers and Operating systems within a significant infrastructure. Know how to follow a process or service within a few sentences. We can create a document from the viewpoint of the reader by listening to the user and offering document(s) based on the best solution.

Technical Writing is – as it explains in the box – technical. We speak to Subject Matter Experts and translate their language into content that a technophobe will understand.

We produce documentation in several formats in such a way, to get the message across to our many audiences. What I have written – you too will be an expert. Give yourself a hand.

Key elements of technical writing

Using a consistent language with regards to terminology.

Creating Glossaries to help readers understand the terminology used within the document.

Formatting document headers with the same font size and tables and drawings labelled the same way are important.

From using Excel spreadsheets, Template creation, document versioning, documentation content and types of material, clear document titles and subjects – working with either a shared drive or a document management system and talking to SMEs every day your average technical author is a ‘rare breed’ indeed.

If you have not already read my post titled “Technical Authors are not easy to find’ we do not attract many candidates.

Technical Writing | Hire a Technical Writer sooner, rather than later

As a Technical Writer with over Twenty Years of experience, I have a question for Project Managers and Subject Matter Experts. Have you ever been involved in planning a project (PCI, GDPR, ISO27001, ITIL) where documentation is critical; if so, how did it go? Crucially, did the project achieve its aims of delivering ALL the documentation? If not – do you know why the plan failed? It could be that you were unable to hire Hire a Technical Writer for advice and guidance.

Why Hire a Technical Writer?

A collective failure of technical / process documentation projects is the lack of knowledge and expertise during the planning and discovery phases. Many project managers and Subject Matter experts fail to grasp the reality of a documentation project. Many projects fail miserably because the planners do not understand the lifecycle of a document. From the initial draft through various reviews and sign-off takes much longer than expected. I regret to say I have met PMs and Consultants that do NOT know the difference between a written process a documented plan and the purpose of the policy. If that is the case, your project could be in trouble.

How long to write a document?

If you ask a Technical Writer how long will it take to write one document, their reply will be – “I do not know”. Technical and Process documentation depending on the project (PCI, GDPR, Operations, ITIL) will have many different requirements and factors which delay the information gathering, the writing and review stages before sign-off.

The likely reality of writing a 30-page document containing:

  • VISIOs (3 or more) comprising between 10 to 30 steps
  • Process narratives (3 or more) of between 10 to 30 steps
  • Appendixes (2 or more)

Will amount to – give or take – at least 8 – 12 weeks of effort before it gets to the review stage. However, the more content the document contains and the more complicated it becomes, the longer it will take.

My advice is not to plan such a project without professional help.

If you are wondering why it takes so long – it is worth noting that compliance projects such as PCI and GDPR generate a lot of documentation. TWs working on large projects could be managing a list of more than twenty documents and every document regarding size and content could be very different.

Hire a Technical Writer

My first word of advice is this – If you have such a plan on the horizon, where the Technical / Process documentation is the primary focus – hire a Technical Writer, not a Business Analyst, to give guidance from the start of the project, NOT when the end date is in sight. The TW can highlight issues, risks and bottlenecks. You will also know what you can reasonably expect to achieve within the allocated time assigned to the project.

The Technical writers will need:

  • a week (at least) to assimilate the project
  • Time for training on any tools
  • access to Subject Matter Experts (SMEs)

Add in contingencies for illnesses, holidays and unplanned absences due to personal reasons and the fact a TW could resign from the project at some point

If the budget and the timelines become fixed (in stone) with multiple documents to complete in a short period, then, consider producing Quality, rather than Quantity.

To ensure quality prioritise, or rank the documents to avoid inconsistency across the documentation set:

  1. Required
  2. Nice to have
  3. Not important

Or use The MoSCoW method.

    • M – Must have this requirement to meet the business needs
    • S – Should have this requirement if possible, but project success does not rely on it
    • C – Could have this requirement if it does not affect anything else on the project
  • W – Would like to have this requirement later, but delivery won’t be this time

Documentation

Who will use them?

  • Documents for external and internal users will require a different level of language
  • What level of information and detail will the audience expect?
  • Does the document need VISIOs?

Additional Points

  • Travel: Will the TWs need to travel abroad or Nationally, if Yes, are they available to go and do they have current Passports/Visas?
  • References: Identify any useable archived documentation.
  • Reviews: decide who will review and who will sign off a document
  • Scope: Could there be any changes which will add to, or change the scope of the project

In summary,

Documentation projects fail due to:

  • poor planning
  • the lack of experience and
  • not allowing enough time to complete the documentation.

Finally: If the success of the project depends on the documentation (Disaster Recovery Plan, PCI/DSS, BCP and ITIL) – why do PMs and SMEs allocate so much of the budget to non-documentation resources?

Technical Writing | A brief guide to documentation projects for Project Managers

A brief guide to managing documentation projects for Project Managers will demonstrate that when done correctly will produce long-term benefits.

Here are some examples to help keep your documentation on track.

The original writer is not the best person to check their documentation because they very rarely spot their mistakes.

  • Arrange for a peer review and/or technical review of all changes
  • establish a review process to make sure the documentation is both factually correct and consistent.

All documentation requires ongoing review once or twice a year.

  • If your company use a Document Management system to store documentation, make use of the “metadata” windows to describe the content changes to make the review process easier and consistent.
  • If you are so inclined adding an index to your document, especially when it is a large document will enhance the documents usability

Like everything else, documents become living information that:

  • Maintaining the documentation represents a significant challenge
  • Without a management policy or agreed procedure, the Documentation you are creating will cease to have any value if it is not updated
  • Documentation requires dedicated resources, in which some companies will not invest
  • In other words, use or contract an experienced Technical Writer

Technical Writing | Why your business needs Technical documentation

Managers underestimate the purpose of technical documentation until they discover they have no relevant documentation. Listed below are 6 reasons why you need technical documentation

  1. Without technical documentation you have no historical record of any project ever completed within the company
  2. You have no metrics against which to measure current projects
  3. You have no information which outlines the lessons learned and the lessons failed
  4. During an upgrade project the team relies on guess-work to get things right . . . it also means the project will take much longer to complete stretching the budget
  5. What documentation there is lies scattered over several drives and only makes sense to the author
  6. Your valued tech staff have left the company taking information with them in their heads

Now you know why Technical Documentation is important; if you recognise one or more of the points above . . . what’s your next move?

Documentation projects, before, during and after

Documentation Projects

Many Project Managers and Subject Matter Experts fail to understand the challenges posed by documentation projects. To lead such a project, you need to know what is important and how you will achieve the goal. What preparations should you make to ensure you complete the project within budget?

Here follows the best advice on the documentation projects, before, during and after.

There are many types of technical and process documentation. If the project is compliance based (PCI, GDPR) concentrate resources on the documentation. Consider hiring a Technical Writer quickly for advice.

Capture the data/content

  • Check the availability of the Subject Matter Experts as well as other team members critical to the project
  • Consider the audience for the documents as that will determine the level and detail of the material.
  • Remember the level of content and information is only as useful as its source and the ability of non-technical audiences to use and follow the instructions/processes

Organise the document and content

Create a standard template with Heading and instructions regarding the level and type of material the TWs need to gather. As a guide use the following headings:

  • Work History
  • Versioning control
  • Scope/Out of Scope
  • Document Purpose
  • Document ObjectiveIntegrate Level 1 to 3 Headings to outline the topics.
    • You can base these decisions according to prerequisite documentation knowledge to provide the master plan for all future written work.
  • Does it require VISIOs/Screenshots?
  • Appendixes

Do NOT waste time creating project timelines to write and produce the documentation.

Until the information and gathering phase begins, do not even consider a guess about how long it will take to complete the documentation.

As the list of titles grows, Management may need to consider extending the budget to finance the project. Abandoning the documentation when it is ‘Nearly there’ will be waste of money, time and resources.

Decide the output format

When the Technical Writer has written the documents, consider which of the following formats will suit the company’s requirements.

  • MS Word stored in a Document Management System
  • PDF stored in a Document Management System
  • *.CHM files created by using such application as RoboHelp
  • Wiki formats: A Wiki provides the user community with the opportunity to provide documentation feedback

Future Review Requirements

Do not overlook the future requirements of any project. All documentation is an ongoing project. Establish a workflow between the IT teams/Process teams and the documentation department to update documentation.

  • Update the documentation when:
  • the IT teams upgrade or modify the Server/Application/technology
  • document all changes, using a change management process to prevent any repeat the configuration
  • align the documentation and the project

Revise the Project

On completion of the project Use the documentation to:

  • reflect the changes and updates
  • test to ensure instructions are clear, concise and correct
  • Avoid considerable time, frustration, and future expense by correctly applying documentation strategies to:
  •  . . . ensure that users can follow the instructions
  • . . . provide a historical record of the changes made during the project
Manage documentation projects before, during and afterClick To Tweet

Technical Writing | The cost of Technical and Process documentation

Why is it that companies view the cost of Technical and Process documentation as an unnecessary expenditure rather than viewing documentation as a centre of knowledge? Management seems to have a blind spot with documentation and conveniently forgets the role of documentation.

When redundancies beckon, I know how quickly management will sacrifice the technical documentation department. When management seeks layoffs, the technical author(s) will be amongst the first out the door. Months later a member of staff points out that the documentation is out of date and follows up by asking: do we have anything up to date we can use?

In sacking the technical documentation team, no one assumed responsibility. Keeping it up to date is left to those least inclined to keep it up to date. They are the people who would benefit most from its upkeep.

The cost of Technical and Process documentation
The cost of Technical and Process documentation

Within a software environment, we easily forget that as the developers progress their software application, it also becomes more complex. Failing to supply up-to-date documentation means customers can overlook many of the improvements and advanced features. We could say the same of any IT department. As the network grows, there are more questions and fewer answers. No one has a good overall knowledge of the network because of the lack of documentation.

Where does that leave technical writers?

However, you refer to us, be it technical authors, communicators, documentation staff or as the font of all knowledge. Never doubt our experience, our people skills, our ability to write clear instructions.  We can explain complex technical terms in easy-to-read formats. Who else will put up with blank stares, sarcastic comments and listen to comments such as “whaddya want now?’ to get what your company needs; usable documentation.

The cost of Technical and Process documentation
The cost of Technical and Process documentation

Remember, it is not about the cost of hiring a technical author. It is about our value to your organisation. Our documentation will keep your staff informed and up to date. There is a point to keeping your processes up to date as your working environment changes. It is also about keeping that software guide up to date enabling your customers to use your product more efficiently and know they invested in a superb product.

Finally, don’t forget that a technical author will not only you save money now but also at a later date and will keep on saving you money, therefore, over the long term justifying their value to your business.

The cost of Technical and Process documentationClick To Tweet