Technical Writing | Sourcing a technical writer

When sourcing a technical writer, you will need to ensure that their experience matches your requirements. It goes without saying that you need to source one who has the right knowledge, background and expertise. At the interview they should aptly demonstrate that experience by way of samples; 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 be building 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 employing a Technical Writer on a permanent basis unless you are sure there will be ongoing work.

Work cycles can and do 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. In my opinion, this is why the position of Technical Writing lends itself more so to contract work rather than permanent work.

To summarise: if you employ a permanent Technical Writer ensure you have plenty of contingencies within the scope of 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 be covering will not go down too well.

A word of caution

Unfortunately, our profession can and does 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 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, when it comes to 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 employing 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 | 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?