Technical Writing – The Survivor’s Guide

This book Technical Writing – The Survivor’s Guide is available through Amazon in paperback and Kindle format contains all the Blogs I have written since 2012.

If you want to know how we work, estimate a project, how we view project managers and our role go ahead. Make my day and buy a copy.

Technical Writing – The survivor’s Guide

The difference between Policies, Standards, Procedures and Strategies

As a Technical Writer, I have written many policies, processes, strategies, standards and related documents. These documents outline how a business operates and provide help when a team member requires a reference.

I worked on a project where the PM insisted a document contained a process. When I said it was a strategy, he threw a hissy fit. He insisted and had no intention of listening. He is not the first who thought they knew better. In the meantime, steam billows from my ears while the consultant continues to sprout opinions on the various documents.

For the uninitiated, here is my explanation of the difference between Policies, Standards, Procedures, Standards and related documents.

Policy document?

A policy sets out an agreed management policy which might refer to IT Security and Risks. However, it will not give any direction on how to execute this vision or strategy.

A set of policies are principles, rules, and guidelines planned or adopted to reach its long-term goals. Management signed policies and published them in the Company’s preferred medium.

    • Writing Policies is to influence and determine major decisions.
    • Processes and procedures are the specific methods used to express policies in action in daily operations.

What is a Process?

It is a task, a procedure – it is NOT a Plan.

The ISO definition of a process is:

A process is a set of inter-related activities that turn inputs into outputs,

You MUST learn the process; know WHY you need it and perform the process end-2-end.

      • Process is a high-level description of a series of inter-related tasks covering an entire business.
      • It is an internal, ongoing process updated annually, as policy guidelines serve as a crucial guide for employees and managers.

Procedure 

A procedure contains more detail than a process but less detail than a work instruction. It tells users HOW to perform sequential tasks to achieve a specific outcome.

Participants will complete a procedure from start to finish in one continuous time frame (no significant delays between steps).

Work Instructions (WI)

A WI contains a detailed description of a task. Its sole purpose is to explain how to do a specific task step by step.

Plan

IT IS NOT a Process

      • Organisations have Management Plans which outline WHAT you are going to do; it does not explain HOW you will perform a task.
      • The Plan determines how to allocate resources and provides backup plans if resources are not available at a crucial time.
      • The Plan document outlines the components to show How a process will work.
      • A plan is how you will move from A to B and should support your strategy by providing a method to reach B containing an acceptable balance of risk and reward.

What is strategy?

A strategy document explains how an organisation will move from point A to Point B.

      • How will you get there?
      • Issues, problems
      • Solutions and tools to get you to point B

A strategy solves the move from A to B, considering any unforeseen issues and problems that may occur to slow your journey to B.

Your strategy is WHAT you want to do.

Understanding the difference between a strategy and a plan allows you to make sound strategic planning decisions that separate the two.

What is the standard?

Standards are mandatory actions or rules that give formal policies support and direction. Writing standards requires a company-wide consensus on what standards must be in place. It can be a time-consuming process vital to the success of your information security program.

      • They are written to show expected user behaviour—for example, a consistent company email signature.
      • Might specify what hardware and software solutions are available and supported.
      • Compulsory and must be enforced to be effective. (This also applies to policies!)

Give us a break

Give us a break. We need it. I write with authority and experience with over 25 years of experience as a technical author. My enthusiasm for delivering clearly defined documentation/content strategy has never diminished. Yet, two common issues remain for which I have no answer:

      • management expects a quick return on their budget, and
      • meeting people who think our role is a waste of time.

Our role is vital, and without us, standards of written and oral communications will forever diminish. Like many technical writers, I have various skills which overlap into different roles. I may operate under the title, technical author, but I have many more job titles under my belt. What skills do you ask? I communicate with many experts and produce relevant policy and operational process documents regarding maintaining a network. While I may not have the technical knowledge, I could step into a role and manage the infrastructure by working with technical teams. 

What can I tell you?

  • Despite the title, we are not technical experts.
        • we are documentation experts; we have an innate ability to understand the technology and explain with help from an SME how it works,
        • analyse workflows and write complex processes with drawings to help teams work more efficiently.
  • our job is never straightforward as we rely on many factors that hinder progress,
  • A change to one document means changes to related documents that contain exact content; writing is not easy:
      • Try writing 300 words about yourself. When done, look closer; how many errors can you see, and what changes will you make?
  • We work with people who are not technical writers.
      • And people who do not understand documentation but have an opinion on how to write and manage documentation.
  • We are not miracle workers:
      • If you expect to see results within a short period based on an issue that has continued unchecked for many years, you will be disappointed.

Many assume we do a cut-and-paste job and do not know that writing and managing reams of content is a fundamental role. If not, companies would not need people like me to make sense of the problem, offer a solution, and complete the job.

What do we do?

I have worked with developers, engineers (of varying shades), and experts in IT subject matter. The majority either:

        • Regard documentation as a luxury,
        • write their documentation, or
        • I do not see the point,

The developers I have met consider technical writing below their pay grade. If you think we are below your pay grade, you need to understand our role and responsibilities. 

What do we offer? 

We link the business and the users by describing the product’s potential. Knowledge management: if the knowledge resides in a team member’s head, get it out before that head moves on. That knowledge is an asset. A skilled communicator is essential to get this work done. We create critical information that is subject to an audit.

        • Writers can help with ITIL, security standards ISO27001 with quality, processes and procedures.
        • They can also help marketing teams with collaterals, white papers, marketing materials.
        • They can create newsletters—internal and external.

Who cares? No one reads it! 

Try telling that to your customers who spend more time calling your helpdesk. If your documentation is not updated and compatible with their version, you will hear loud and clear complaints. 

Businesses forget their T&Cs contain a clause that explicitly clarifies providing documentation. 

Relax at work! 

We get little time to relax because we’re always looking at ways to improve the documentation quality. It is not a standstill role. As colleagues overlook us in many stages of the development, the release phase can be daunting due to:

      • Last-minute functionality changes,
      • managing un-realistic situations,
      • unrealistic deadlines,
      • Multitasking—working on other vital projects.

This profession has a high level of stress due to a lack of communication. Managers expect the documentation to be ready and available within a few hours. Sorry, unless you have a mega team of technical writers, that will never happen.

Documentation review can wait. 

If that is the case, you must make documentation an integral part of the software development life cycle (SDLC). It will help to:

      • Include the documentation review in the schedules of the reviewers.
      • return review comments to writers on time,
      • Writers are aware of necessary changes before deadlines to make the required modifications.

People assume technical writers only write and think it’s a straightforward job. The importance of technical writing will come when they understand:

      • The actual work we do, as technical writers,
      • the management of multiple issues to enable the completion of a project,
      • the process of documentation is also a process of quality control.

Be aware of your technical writer(s) and what they do to make you look good. Do technical writers work? A technical writer performs many other tasks and related activities as a part of the documentation process:

      • Multitask: work on multiple projects at different stages of completion. 
      • Organise: keep projects to prioritise the work,
      • Be patient: deal with deadlines,
      • Manage: track multiple documents and content.
      • Training: train staff in communication and writing skills.

An SME can do the job just as well. That is debatable:

      • SMEs have their responsibilities, and documents are way down their list
      • gaps in the content are common because they don’t believe certain functions are worth mentioning.
    • A technical writer will revisit the documentation, test for cracks, and add missing content.
        • professional technical writers are: 
        • more efficient, 
        • produce high-quality documentation,
        • structure documents for consistency,
    • design easy-to-use information, and
    • Perform other related writing activities.

My advice, take technical writers seriously, and everyone will be happy.

A virus made us do it …

Are you among the many who, during lockdown, have wondered what the future may bring? Do you clearly envision what is personally meaningful and how you will change your life once the pandemic ends? 

Depending on your point of view, lives will change for the better or poorer.

I’ve thought a lot about what should change, and here are my thoughts on possible future events.

The government has learned a huge lesson: when a crisis looms, act immediately. 

Why does the government lack a pandemic strategy?? The government needs an effective strategy tried and tested at least once a year. Perfect preparation prevents poor results.

The UK needs to reduce its dependence on international supply chains and be ready and capable of producing what we need when we need it. Self-sufficiency.

The contamination risk of stockpiling PPE in enormous warehouses renders the material unusable. The government requires a list of businesses that can quickly switch to producing PPE supplies.. 

When the government negotiates BREXIT, there is much to consider, such as our diminished skills base. We need a state-funded education program to train various professionals.. We don’t need a constant stream of graduates with non-degrees.

Britain allows foreign competitors to purchase UK companies and shift operations overseas, resulting in billions of lost revenue. Smaller UK manufacturers closed, as there was a cheaper version worldwide. 

We need to rebuild our industrial base to reduce our reliance on foreign markets.. If not, what happens if we need immediate access to vital goods and discover we can’t purchase any because of global demand?

People and businesses will demand cash to save their businesses, although many are on the verge of collapse. The government must focus on what will thrive and benefit the UK economy. 

 Not only will the NHS receive more cash but also the Police and education. I suggest the NHS needs reform because, without it, the entire organisation becomes a financial vacuum. 

Pollution levels have dropped. Step outside and look at the blue sky. How fresh is the air? Also, I live below the flight paths to Heathrow and Luton, and there are no visible vapour trails in the sky. 

 Now we have a feel for a cleaner world. What are we going to do about it?

We could start with substantial investment in developing electric cars and renewable resources. Don’t forget to invest in electric vehicle infrastructure. The casualties would be the oil-producing countries who would lose vital revenue. Let’s not forget the government would lose billions in tax on fuel sales. Going green will be great for the planet, but the government will raise taxes. Talking of which…

… I foresee the government hiking PAYE and corporation tax by up to +-7% to claw back the money it spent during the pandemic. There may be very little hiding room for corporations who have evaded paying their ‘fair share’ since 2008. However, when raising taxation, the government treads a thin line. Tax is a sensitive issue and will not please many Tories, although I can’t see Labour having a problem with such actions. 

As for Future holidays, it will be a staycation. I recommend a fortnight in the West Country. Airlines may not return to normal for years, fewer and more expensive seats due to failures..

The Office Culture

Many businesses allowed their staff to work from home. It would not surprise me if CEOs and Directors had discussed with HR that possibility in the past but didn’t allow it for productivity reasons. By now, I’m sure many CEOs, jobsworths, and bosses have realised their businesses can operate and not suffer without the staff at desks. 

Could home working become the norm?

CEOs could cut costs by decentralising London operations.. Doing so will give the CEO access to more applicants who wouldn’t move to London. It will be a significant benefit to Employees who rise and shine, have breakfast, and sit at a desk in their home, or maybe work closer to home on a short commute. 

If the company bosses seek to lower salaries in a few years because of no longer needing to travel to work, it won’t be a surprise.? 

On a personal note, by not travelling to London, I’d save the following every week:

  1. train fares (Oyster £75.50)
  2. driving to Amersham parking (30 miles round journey; 5 X 6miles)
  3. parking (£36.00)
  4. lunch and coffees (£60.00; 2 X Coffees and lunch of £6 per day)

Not everybody can work from home. Employees of the NHS, emergency services, hospitality, retail and transport services will always be in the ‘office’. However, with trains and buses carrying fewer commuters, there will be more room available. Tourists will find it easier to use the London Underground to visit tourist attractions.

House Prices in London: 

If large companies decentralise their operations away from London, or any major city, house prices would drop. Who wants to live in London when there are higher paying jobs and better standards of living elsewhere??

So, here follow a few final thoughts.

  1. If fewer people move to London, could it solve the question of affordable housing?
  2. Less congestion on the roadways and motorways means less damage to the roads and fewer accidents.
  3. with lower pollution levels, the NHS will see a decline in patients with respiratory problems.

The above are my views, and there are many more I could add. No doubt readers will point out their thoughts. I believe change is coming, like it or not. Much will depend on how we, as citizens of the UK.

Content and Documents | How Can I help you?

In the aftermath of Coronavirus, many managers may know they have documentation projects in the pipeline and, on their mind, is hiring a technical author. As a contract Technical Author with 20 years plus experience, what can I offer you?

What type of documentation will your project need?

With the documentation, I would advise you NOT to delay even now and start any discovery phase to identify which titles you need to prepare.

How can I make your project run with more ease?

I have a vast collection of generic documentation covering PCI, ISO27001, GDPR, ITIL. Hence, with some tweaks and by understanding your requirements, my generic documentation can be tweaked to suit your company’s needs, which will save time and money.

Compliance projects

Compliance projects generate more documentation than managers expect. If you have not already performed a discovery or due diligence phase, you could have up to 60 titles to write ranked in order of importance.

  • Payment Cards Industry (PCI)
  • ISO27001
  • ITIL and ITSM Policy and process documentation

Confluence and SharePoint

Do you use either confluence or SharePoint, or both?

Have you lost control of the content/documentation?

Has the structure in Confluence been overridden by numerous spaces that are no longer valid, filled with legacy content and no ownership?

Poorly written content and documents can hamper productivity and lead to mistakes. You may need an expert eye to look over your content and documents and identify what is no longer needed and seek to slim down the information in either.

Transformation

Are you about to start a transformation project and have discovered the documentation has no value? Stress not. With help from SME’s and a series of interviews, the documentation will soon be underway. I wrote a booklet on such projects. Read it. To help start the technical documentation, I have the following templates:

  • Operating templates
  • Installation guides
  • Profile document
  • Technical procedures for management

Disaster Recovery and Business Continuity

I have a collection of templates that can help get a plan up and running after consulting with your staff.

Call Me 07534 222517

Email: twriter201@gmail.com

The most excellent technical writer

As Technical Author, an interviewer asks what makes a good Technical Author. Based on my 23 years of experience, here is my take on what makes either a poor, a good or an excellent technical writer.

Poor technical writers edit the content and leave it at that. There are no questions, no curiosity, even when instructions do not read correctly. In which case, if that is, you start looking for a new job.

Good technical writers :

  • Logically set out the steps starting at A and avoid no detailed Work Instructions leading to Step Z.
  • Methodically test the steps
  • ensure the content is easy to read and understood by reviewers
  • They know their ABCs

Excellent technical writers go a step further – we:

  • ask why – who – what – when – where, and how
  • analyse the problem the user is experiencing  
  • ask how the documentation will solve the problem
  • anticipate the issues users could encounter and the questions they will ask when they follow the material.
  • Build relationships with teams across the floor
  • Use humour and diplomacy to get what we want
  • Pretend we are a user reading the document for the first time
  • include links to related topics to keep the user briefed

All the above takes time, effort, and creative thinking, but as excellence is a byword, we never feel the pain.

By covering the above points, the documentation will positively impact the business. Excellent documentation boosts user adoption and reduces support services..

Project Management and Documentation

Poor project management has a major impact on technical documentation. In other words of you don’t listen to me, we will be up to our necks writing and managing techdocs while everyone else has their feet up and enjoying a few beers. This article delves into the intersection of project management and technical documentation. 

Put a plan around a project or a project around a plan.

Without a proper project plan, technical documentation is at risk of failing.. Those without experience tend to alter objectives and add to the project without heeding the technical writer’s experience and advice.. 

Documentation alone cannot replace a plan, but it can aid in rescuing a struggling project. Taking the time for documentation analysis can help the project by reducing risks and increasing quality..

Frustrated

Experienced technical writers may become frustrated when the project timeline is unrealistic. This happens when:

  • working with staff members who have no experience working with documentation and assume it’s a straightforward task
  • unworkable deadlines that sacrifice documentation quality and lead to frustration among internal parties

It is worth bearing in mind: 

  • Rely on the TA’s knowledge to schedule technical documentation and establish a timeline.
  • Writing or migrating content is not an instantaneous process; a failure to work with the writers could lead to counterproductive problems. 
  • If the timeline is genuinely tight, develop a list of documentation priorities for users to adopt the product.

A typical breakdown for a technical writing project includes:

  • Research the underlying technology and related issues required for the documentation effort.
  • Dedicated time for writing.
  • Dedicated time for editing. Copy editing and editing for style, clarity, and other issues.
  • Dedicated time to review the technical accuracy of the documentation. Never assume that a document is correct. Always create review time for accuracy by SMEs.

Allow sufficient ramp-up time

Technical writers need sufficient ramp-up time to become versed in the product. While ramp-up time is relative, depending on the writer, a project manager can support the writer:

  • Supply the technical writer with the hardware and software quickly..
  • Provide the system access, usernames, and passwords.

Ramp-up time for technical writers is beyond the learning curve.

Review the reviewers

As a technical writer, it is important to maintain the accuracy of your documentation. Include the time for technical reviews in the project schedule..

  • Scheduled time for technical staff, project managers, and other reviewers to review the documentation.
  • Time for the technical writers to add the revisions to the documentation.

Can project managers and technical writers get along?

Technical documentation of superior quality necessitates the involvement of technical writers. Effective collaboration between project managers and technical writers can cause improved design and customer support.. Having customers who can solve their own problems without contacting customer support can benefit a company.

 

Technical Writing | General Data Protection Regulations

GDPR

On the 25th May 2018, the new General Data Protection Regulations (GDPR) came into force.

Companies outside the EU

If your Company actively trades within the EU and stores, processes or shares EU citizens’ data, then GDPR does apply to you.

Compliance and documentation

One of the primary rules is that under GDPR Process activities MUST be documented.

Companies are required to maintain a set of Policy, Process and Plan (PPP) documentation to ensure you have evidence to support your claims should the ICO investigate any complaint or breach of data.

Note that the Information Commissioners Office (ICO) could demand to see the written documents

What do you need to consider?

As a technical writer, with experience writing compliance documentation, what can I tell you?

If you are still struggling to start

My Blogs are clear, writing one document, when there is a substantial list to be completed from scratch to sign off is a lengthy process. Even if your department has documents that can be reused, it will still take a long time. Compliance projects are manually intensive and documenting GDPR will need dedicated resources.

My experience could be necessary to help you write and manage those documents. The sooner you contact me, the sooner we can start the road to compliance.

  • Create a standard template with – Statement, In Scope, Version Control, Change History, Distribution Lists, Roles and Responsibilities
  • All PPPs must adhere to GDPR – include in the document ‘The purpose of the document’, ‘The Scope’ and add a list of the GDPR compliances relevant to the PPP you are writing and explain the WHY the company are complying along with the HOW the company will comply.
  • The documentation must be relevant to your business. Generic documentation outlining a PPP will NOT suffice
  • Complete the documentation – do not start and leave a document incomplete then sign off; an incomplete document could fail a Compliance Audit
  • Maintain the detail – do not half explain a process or policy
  • Structure the documentation to avoid duplicating information over several documents
  • That the documentation may need to be ISO 27001 compliant

Does Your GDPR Project need documentationClick To Tweet

 

Technical Writing | Project Managers and Technical Writers

Project managers and technical writers, two distinct roles. One of my many skills as a technical writer is organisation. We juggle many tasks and switch between them with ease. People skills are important as we speak to coders, engineers, and technicians of various shades. In the meantime, we manage a ream of documentation while taking instructions from SMEs. Occasionally we meet a project manager who has had minimal exposure to technical documentation as part of a project.

techwriting
Project Managers and Technical Writers

If you lack experience planning the technical documentation component of a project I suggest you consult with your technical writer. A working collaboration between project managers and technical writers can help organisations reap the benefits of the project (because it’s documented), and provide better internal and external support through documentation.

If you are one of the many Project Manager who has never worked with Technical Writers, remember we are professionals.  We will not tolerate the viability and quality of the technical documentation to satisfy the needs of others.

Techwriting
Project Managers and Technical writers

So, if you have no direct experience with documentation or Technical Writers consider:

  • Talk with your TW(s) because their experience will provide you with a much-needed background in document management.
  • To help plan the documentation, avoid creating timelines as you progress the project.
  • TAs cannot pull documentation from a hat or generate a document from code.
  • Speak to the TW(s) to gauge how long it will take to review/write/edit a document. In my experience, many project managers overestimate the timelines or worse underestimate the deadlines. Always build in flexibility to allow for problems in the documentation process
  • Reviewing a document intended for transformation containing more than 20 pages plus will take time (the general rule of thumb is one hour per page).
  • The time required for writing
  • Peer reviews
  • Time to have the content technically reviewed

Technical Writing | Passive vs Active Sentences

What is a passive sentence?

A Passive sentence is a grammatical voice prevalent in many of the world’s languages. In a clause with a passive voice, the grammatical subject expresses the theme or patient of the main verb – that is, the person or thing that undergoes the action or has its state changed.

http://en.wikipedia.org/wiki/Passive_sentence

Passive vs Active

I can already hear readers asking, what is a Passive Sentence?

Here goes!

Compare these sentences.

  1. The Application is used to collect data (passive)
  2. Use the application to collect data (active)

or

  1. The key was used to open the door (passive)
  2. Use the key to open the door (active)

or

  1. The wire is fed through the box by the electrician (Passive)
  2. The electrician feeds the wire through the box (active)

Using the active voice, sentences provide a clearer more effective message in technical writing and business writing. The active voice identifies the action and determines who performs that work. For clear examples of passive voice look at government documents, which gives the wording a dull, bureaucratic tone.

Over time, writing in the passive voice becomes a habit, one we should all work to change. Of one thing I can be certain, despite the debates, I will continue to use the active sentence.

Technical Writing | Technical documentation vs Helpdesk