Why you need a Technical Author

As a Technical Author, I have always heard it said that: ‘anyone can write so “why you need a Technical Author?”

What is Technical Authoring?

Technical Authoring like many jobs has many facets to it. The fact you see Author in the title suggest to the uninitiated that primarily we write. You could not be more wrong! There are many facets to our job and the writing takes only a fraction of the time allocated to the project.

Our time is taken mostly sourcing and recording information. We then analyse the information and then use what we have for content. The following points are important:

  • Communication skills
  • the ability to understand technical concepts
  • Use a variety of tools to create well-structured documentation that an audience uses
  • write for a specific audience

Let’s get to the point

Technical Authoring 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 badly written technical documentation. A user wants to read the document and go ahead with confidence and/or understand the function of multiple servers and Operating systems within a large infrastructure and/or explain a process or function within a few sentences. We can create a document from the viewpoint of the reader simply by listening to the user and offering a document(s) based on the best solution.

Technical writing is – as it explains on the box – technical. Apart from writing, our role is to understand Subject Matter Experts, written technical material and translate that content into a language that a technophobe will understand. It also helps if a technical author can verbally explain the material or present it in a diagrammatical form.

Of course, to explain the technicalities of a software product, a gadget, an App, or a significant IT infrastructure – we must understand the concept ourselves. We cannot explain what we do not understand.

So, for our audiences out there we produce documentation in several formats in such a way, to get the message across to our many audiences. Therefore, after what I have written – you too will be an expert. Give yourself a hand.

Key elements to technical authoring

Using a consistent language with regards to terminology and 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’ you will find that should you need our ability – it is a profession which does not attract many candidates. That is another discussion!

Posted in documentation, technical writer, working with a technical writer, writing technical documentation | Tagged , , , | Leave a comment

Documentation vs Support

Documentation vs Support

When users cannot find a solution to a problem with an application, they will read the official documentation. If the documentation does not have the answer, they then access on-line forums. Finally, when all else is exhausted, their patience is lost, and their disillusionment with the product is at an all time low, then, they call support!

I have experience in premium line support and have heard many an angry voice venting over the phone line. A customer’s frustration leads to subjective complaints about the company and the guilty software.

  • 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 seem to belong to my version of the software

When documentation fails to deliver the answer, support receives more calls which impact directly on their costs. Companies can charge for Support, but remember that customers who feel forced to call Support due to inadequate documentation can hold mixed feelings about the product and company.

Frequently Asked Questions (FAQs)

As an experienced technical writer, I know that documentation will always need more to satisfy the demands of customers. One method I facilitated was to provide a feedback option, whereby I invited users both internal and external to point out – where in their opinion – the documentation appeared vague.

Using that feedback, I approached the developers and helpdesk who provided a more detailed solution based on their knowledge and experiences. I not only created a FAQs knowledge base (or Wiki) for external users but placed the information in the documentation. The internal staff received the content via a *.chm file created using RoboHelp. The FAQs were a success and helped cut calls to support by 80% as we were creating searchable information that was easy to find and accessible by all staff.

An experienced technical writer knows what the audience expects and produces an audience focussed document. At the end of the day, the purpose of the document is to help users complete their working day productively and efficiently.

I have said before and will repeat the following: ‘treat your documentation and your information as an asset’ It is worth the time and money to get it right and to maintain the proper format. The savings when it comes to Support can be significant. As a nice side benefit, your users will be happier.

Posted in technical writer | Leave a comment

The consequences of poor technical documentation

Any technical writer will tell you that technical documentation is often the last job on the project manager’s list when an updated product or new product is due for release. If the required documentation is not current or full of holes what are the consequences of poor technical documentation?

Kill the myth

If you work in a software environment, let me kill a myth for those who think their customers ignore the documentation. They DO read it and USE it. When they fail to find a solution to a problem within the documentation, I can guarantee your support function will soon be ringing.

Why is the documentation full of holes?

I have worked in several software environments and am aware of the problems the developers, encounter along the way. There will be many events and decisions leading up to the release of the product. However, the developers and PM, in their efforts to meet the release date ignore an important team member – their technical writer.

The software journey in part

What could happen during the development stage of the product that leaves the technical writer floundering?

  • It passed through multiple phases of a redesign, change of goals and added extras
  • Time constraints saw many features and functionality discarded
  • when the product release date came and went, the technical writer did not have to hand a list of all the changes as the developers and PM never shared the information
  • the PM and developers considered the product documentation as a ‘nice to have’ while others regarded it as a non-essential part of the product

During my time in a software environment, the above four points in the run up to version release were regular. I was contending with personalities who did not see documentation as an essential part of the package. Let us be clear – when a company dispatches a product without documentation, it is an unfinished product.

If the imminent software release is a revamp of the product, the company will offer, at a premium price, training courses. The customers who rely on the product pay the fees and select the staff they want trained. The training course includes documentation with a limited explanation of the new functionality and capabilities – not enough to use when a process becomes more complicated.

The irony of not supplying documentation

Here is the irony that companies overlook concerning documentation. I have worked in two software companies where the company’s Terms and Conditions of sale explicitly stated that they include documentation as part of the price. By not supplying documentation the company falls foul of their small print.

It is out of date and belongs to a different version

Out of date documentation is no better than no documentation. Despite the disclaimers stating that the company is not responsible for any inaccuracies within the content, customers will expect correct documentation.

I worked briefly for a Watford based software company in the late 1990s. When their technical writer resigned, they decided not to replace him. In the meantime, the software progressed by two versions. When several customers complained that the documentation did not include references to the many new features the company set out to find a new technical writer and eventually they employed me. My task was to complete the documentation for the two versions. It took some time as I had to make numerous changes to the format, and add many new features – but I got there.

My efforts, however, were rewarded when a major customer met with our developers to discuss customised enhancements and query the out of date documentation. The customer was more than pleased to see the documentation was not only current but also remarked that the standard was much higher than expected, it was easy to understand, easy to use and explained many interfaces that my predecessors had omitted.

The next step

So, once again, if you do not use the skills and experience of a technical writer to write your company’s documentation then maybe it is the time you did. Remember, it is not about cost but our value.

Techwriting

Posted in technical writer | Tagged , | Leave a comment

ITIL Operating documentation

Introduction to ITIL operating documentation

ITIL offers a standard and widely accepted approach to managing business and IT services.

Challenges in Service Operation

The key problem in service operation is the delivery of daily services whilst maintaining value. Services staff need an overall view of the service operation to manage threats and to secure the service. The challenge is to offer an end to end service that includes the business perspective and technical point of view, not just the separate components or ‘silos.’

Benefits of adopting ITIL for Service Operation

Selecting and adopting the best practices in the Service Operation publication will help an organisation to deliver significant benefits such as:

  • Reduce unplanned resource and costs through better handling of service outages and identification of their root causes
  • Enable the business and customers to add value from the services they are receiving by reducing downtime
  • Facilitating continual improvement and better investment decision-making by providing operational results and data for decision support
  • Enable users to improve their productivity or the quality of business services and products by providing quick and efficient access to standard services
  • Meet the aims of the company’s security policy by ensuring that IT services will only be accessed by those authorised to use them.

ITIL Operating documentation is essential to:

  • Support activity planning (Capacity and Configuration Management
  • Manage growth / time to market (Change Management, Release and Deployment Management)
  • Reduce error rates (Commissioning procedures, Quality Assurance, Checklists)
  • Conform to Regulatory and Compliance requirements (Health & Safety)
  • Maintain Security Levels (Information Security, Access Management)
  • Risk Reduction
  • Operational activities (Event Monitoring, Incident Management, Request Management, Infrastructure Support)
  • Knowledge Management (CMDB, Knowledgebase)
  • Simplify access to information (online information and forms)
  • Communication of effectiveness measures (CSFs, KPIs and Management Reporting
Posted in documentation | Leave a comment

The role of a technical writer

Technical writers are professional writers who write technical documentation to helps users understand a product or service. What is the role of a technical writer?

Unlike novelists and journalists, technical writer’s are anonymous. There is no description of us as a writer. Our names do not appear in the final published documentation, neither do the names associated with the document. Technical writing has a characteristic and a style of its own that concentrates on a theme and a set of written instructions to help users.

Technical documentation includes the following:

  • Process manuals
  • installation guides
  • User manuals
  • Reports of analysis
  • Disaster recovery plans
  • Operating documents

A good technical writer can make a difficult task easy and can quickly explain a complex piece of information.

My role as a Technical Writer

I have over 20 years experience as a technical writer. My role as a technical writer is to primarily take information from a variety of sources, including Subject Matter Experts (SMEs) and turn that information into a useable document. It may come as a surprise that writing is a small part of our job.

I also develop content to help a company enhance its productivity and provide a range of services to clients who are looking to improve, redesign and, update their documentation.

The purpose of a technical writer when approaching a new technical writing project is to make sure that we keep a focus on what we are writing. By sticking to the core principles of technical writing, we ensure that the reader understands the documentation.

Writing with consistency, clarity, and clear vision

We may all speak English, but let’s be clear not everyone knows how to write clearly and to the point in plain English. I keep each sentence to the point, avoid verbosity and present everything in a logical sequence. That is the job of a technical writer!

Posted in documentation, technical writer, working with a technical writer, writing technical documentation | Tagged | Leave a comment

Unlike a novelist, a technical writer is anonymous

There is a simple reason why that unlike a novelist, a technical writer is an anonymous writer – if you want to know why – carry on reading!

A local Cafe owner introduced me as a writer to a romantic novelist who asked: “are you published?”

I replied: “More times than I can count.”

She frowned with the hint of a smile before enquiring. “You must be a prolific writer. What is your genre?”

“I write Technical Manuals, which explains how technology works. However, unlike yourself, I am what we call the anonymous writer.”

Her husband pipes up: “Don’t worry, he is not a local rival who writes romantic novels.” The look of relief on her face said it all as her husband concluded, “The chances are you wouldn’t understand what he was writing about.”

The Anonymous Writer

As a technical writer, you will not find my written work on any shelf in a bookstore or Amazon with my name on the front page.  That is because the published copy will not list my name. Before the customers or end-users receive the document someone will remove any reference to my name and my collaborators. The company then assumes ownership for the content and any rights conferred on the document, making me the anonymous writer!”

IMG00031-20100408-1502

What defines a technical writer as opposed to a novelist?

  1. Despite the title, Technical Writer/Author writing takes up a small percentage of our real role
  2. a lot of the time our work is not mainly technical
  3. we use around 90% our time researching, talking to SME’s and analysing information
  4. very few people bother to thank us for our work
  5. finally, many IT professionals still think that we produce documentation from a magic hat.

The anonymous writer could help you solve long-term documentation problems and resolve many ongoing problems.

Finally – most of the technical writers I have met are failed novelists or are yet to write that novel and land that publishing deal. I know that, as I am one of them hoping to land that publishing deal.

Posted in documentation, technical writer, working with a technical writer, writing technical documentation | Tagged , , , | Leave a comment

The language of Techspeak

What is the language of techspeak? Could it be a foreign language? When you hear it what do you do? Do you use gestures, or raise your voice in the hope that the speaker will understand you?

So, what would you say if I told you that techspeak is the language of Information Technology? Like many jargon-specific languages, it stands out. So, as an experienced Technical Writer well versed in the tongue of techspeak my advice is simple, if you want to understand the language of Techspeak do the following.

Do as I do and ask

A teacher once told me that there is no such thing as a stupid question; ask that teacher the question and receive an informed answer, or, either search Google or read a book.

Put Your Vanity Away

When I entered the world of Technical Writing within a software department, I had to learn a new vocabulary. The fact is as a Technical writer when I walk into a new environment I must learn a new company specific jargon. Therefore I always make it clear to the person doing the company induction; don’t use company-specific jargon, because I won’t know what you mean.

Do not let your vanity stand in the way. How many times have you attended a training course or induction only to discover later you still nothing!

Remember, you are Not a techie

Of course, there are those who always think they know more than they do. Indeed it would help in many cases if people knew the limits of their knowledge. Unless you are training to be an engineer or a developer and genuinely know something, which the trainer mentions and need to clarify certain points then fantastic. However, if not then listen and learn. Trying to sound clever does not help whomsoever is explaining the detail. I have become frustrated when I am mentoring someone who apparently thinks they know it when they don’t. It meant that I had to repeat myself until the facts stuck.

The technical writer’s point of view

We live in a constant state of learning and development, and if you choose to embrace technology, you will find that you too will enter that world. When an SME cannot supply me with the information I need – my best friend is Google. But, be careful not to get carried away with the amount of information on offer – learn to filter the information.

I visited an old friend who had an interest in computers. Her husband, a man who belonged to a generation when technology was for mathematicians and scientists, baulked at the idea of a computer in the house. In his mind, it would cost thousands of pounds to help her use the technology. Following his death she bought a second-hand book titled. ‘IT for Dummies,’ she followed up with a few more books before the purchase of a laptop. During our conversation, she remarked, ‘I don’t know how I managed without a computer.’

She learnt how to use email, use YouTube to get to play a tune on her piano, acquire new recipes and read up on topics in which she has an interest. My friend is also partially sighted; in fact, the technology is helping her more than she ever hoped!

Posted in documentation, working with a technical writer, writing technical documentation | Tagged , , | Leave a comment