Hire a technical writer sooner, rather than later and save the project money

Here is a question for Project Managers and Subject Matter Experts.

Have you ever been involved in planning a project where documentation is critical; if so, how did it go? Crucially, did the project achieve its aims of delivering ALL the documentation?

A collective failure of technical / process documentation projects is the lack of knowledge and expertise during the planning phases. If you ask a Technical Writer how long will it take to write one document, their reply will be – “I do not know”, because Technical and Process documentation depending on the project (PCI, Operations, ITIL) will have many different requirements and factors which delay the information gathering, the writing and review stages before sign-off.

The reality of a documentation project will be very different from the guesswork and theory. Many project managers and Subject Matter experts fail miserably because they fail to understand the lifecycle of a document. From the initial draft through various reviews and sign-off takes much longer than expected.

This is the likely reality: a 40-page document containing:

  • VISIOs (2 or more)
  • Process narratives (2 or more)
  • Appendixes (2 or more)

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

If you are wondering why it is worth noting that TWs working on large projects could have a personal list of up to twenty documents to complete and every document regarding size and content could be very different.

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 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
  • 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 50 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

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?

Posted in technical writer | Leave a comment

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