Author: Michael Clark

Why People Resist Writing Technical Documents

People do not avoid technical documentation simply because they dislike writing. They often resist because documentation exposes knowledge, risk, gaps, ownership, and accountability. This article explores the psychology behind that resistance and explains how technical authors and information managers can make knowledge sharing safer, easier, and more useful.

Tweet
Pin
Share
0 Shares

The psychology behind writing technical documents is not about writing. It is about identity, control, risk, confidence, workload, and trust.

Resistance to operational documentation stems from people’s awkwardness. They resist it because documentation exposes what they know, what they do not know, and how well their work holds up in writing.

Why are people reluctant to share knowledge?

1. Knowledge is power

In many organisations, people become valuable because they are the only person who knows how something works.

      • They know the system’s history.
      • the workaround.
      • which server talks to which database
      • “don’t touch that on a Friday” rule.

Writing that can feel like giving away their leverage. Documentation makes some people fear they will become less important.

That is rarely true, but the fear is real.

2. They fear being judged

When knowledge stays in someone’s head, others cannot challenge it. Once it is written, others can question it.

People may worry:

      • “What if I explain it badly?”
      • “What if someone spots a gap?”
      • “What if I have been doing it wrong?”
      • “What if this becomes evidence against me later?”

Technical documentation makes hidden practice visible. That can feel threatening.

3. Experts often do not know how much they know

A subject matter expert may say, “It’s obvious.”

It is obvious to them because they have years of context in their head. They forget what it was like not to know.

This is called the curse of knowledge. Experts skip steps, assume background understanding, and leave out dependencies because those things have become automatic to them.

That is why asking an expert to “write the process” often fails. They know the process too well to see where a new user will fall over.

4. They think writing is not their job

Engineers, analysts, developers, support staff, and project teams often see writing as admin. They may think:

“My job is to fix the thing, not write about the thing.”

This is where organisations go wrong. Documentation is not clerical work. It is part of operational control, support, continuity, audit readiness, training, and risk reduction.

The problem is that many organisations only value documentation after something breaks.

5. They have been burned before

Some people have contributed to documents in the past and seen nothing happen.

      • They gave information.
      • No one reviewed it.
      • No one published it.
      • The document disappeared into SharePoint.
      • Six months later, someone asked them the same questions again.

After that, they stop engaging.

Reluctance is sometimes not laziness but disappointment.

6. They do not trust how the information will be used

People may worry that documentation will be used to:

      • blame them after an incident
      • prove non-compliance
      • expose shortcuts
      • remove their ownership
      • offshore or automate their role
      • support a restructure

If the culture is punitive, people will protect themselves. They will give partial answers, vague explanations, or just enough information to appear cooperative.

7. Writing creates cognitive load

People underestimate how hard it is to explain work clearly.

Doing the task and explaining the task are different skills. A person may be excellent at resolving a complex system issue but poor at turning that knowledge into a structured procedure, support guide, recovery plan, or knowledge article.

They may not be unwilling. They may simply not know where to start.

What information managers and technical authors can do

The answer is not to keep saying, “Can you send me the process?”

That rarely works.

The better approach is to extract, shape, validate, and govern knowledge.

1. Stop asking people to “write the document”

Ask them to explain the work instead.

A technical author or information manager should make the task easier by saying:

“You do not need to write this. Talk me through what happens, what can go wrong, and who needs to know. I will structure it.”

This removes the pressure. The SME becomes the source of truth, not the person responsible for producing polished documentation.

2. Use structured interviews

Do not ask broad questions such as:

“How does the system work?”

Ask controlled questions:

      • What triggers this process?
      • Who owns it?
      • Who performs it?
      • What systems are involved?
      • What access is required?
      • What are the dependencies?
      • What happens if this step fails?
      • What evidence proves the task is complete?
      • What must never be done?
      • Who needs to be notified?
      • What is the escalation route?
      • What documents or records are produced?

Good documentation comes from good questioning.

3. Make knowledge sharing safe

People share more when they know the purpose.

Explain that documentation is not there to catch them out. It is there to protect the organisation and reduce repeated interruptions.

A useful message is:

“The aim is not to audit your memory. The aim is to stop the business depending on memory.”

That distinction matters.

4. Turn experts into reviewers, not writers

Most SMEs are better at reviewing than drafting.

A practical model is:

      1. Technical author interviews the SME.
      2. Technical author drafts the document.
      3. SME reviews for accuracy.
      4. Information manager checks structure, metadata, ownership, and control.
      5. Document owner approves.
      6. Document enters the review cycle.

This respects the SME’s knowledge without forcing them to become a writer.

5. Show people what poor documentation costs

People respond better when documentation is linked to real pain.

For example:

      • repeated support calls
      • failed handovers
      • slow onboarding
      • avoidable incidents
      • audit findings
      • change failures
      • disaster recovery confusion
      • project delays
      • dependency on one person
      • duplicated or contradictory processes

The argument should not be “we need documents.”
The argument should be “this is the risk we carry without them.”

6. Make contribution easy

Do not give SMEs a blank Word document.

Give them prompts, templates, checklists, diagrams, or short forms.

For example:

Instead of asking Ask this
Write the procedure. Give me the trigger, steps, exceptions, and escalation route.
Document the system. List the components, owners, dependencies, interfaces, and support contacts.
Update the knowledge base. Tell me what has changed, who it affects, and what users need to do differently.

People will contribute when the task is specific.

7. Use workshops, not email chains

Email is often a poor way to gather knowledge.

A short workshop can achieve more than three weeks of chasing. Put the right people in a room and map the process live.

Use:

      • process maps
      • whiteboards
      • dependency diagrams
      • RACI tables
      • system flow diagrams
      • incident timelines
      • “what happens if…” scenarios

The technical author captures the conversation and turns it into controlled documentation afterward.

8. Recognise the contributor

Knowledge sharing should carry status.

A simple contributor section, review credit, or acknowledgement can help. People are more likely to share knowledge when they feel their expertise is being recognised, not harvested.

The message should be:

“Your knowledge is important enough to become the organisation’s standard.”

That is a very different message from:

“We need you to fill in this template.”

9. Link documentation to governance

Information managers should make documentation part of normal business control.

That means every critical document needs:

      • an owner
      • version control
      • review date
      • approval route
      • classification
      • metadata
      • retention rules
      • change history
      • access control
      • review evidence

Without governance, knowledge sharing becomes a one-off exercise. With governance, it becomes part of how the organisation operates.

10. Use AI carefully

AI can help turn rough notes, transcripts, and SME interviews into a first draft. But it must not become a substitute for validation.

A good model is:

      • record or summarise the SME discussion
      • use AI to create a structured draft
      • technical author edits for clarity and usability
      • SME validates accuracy
      • document owner approves
      • information manager controls publication and review

AI helps with speed. It does not replace ownership, accuracy, context, or accountability.

The real role of the technical author

The technical author is not merely “the person who writes it down.”

A good technical author acts as:

      • interviewer
      • translator
      • editor
      • sceptic
      • user advocate
      • information architect
      • risk spotter
      • governance partner

They turn messy, partial, expert knowledge into something usable, controlled, and repeatable.

The information manager then ensures that the document does not decay into another forgotten file.

The key point

People are reluctant to share knowledge because knowledge is personal, political, and protective.

The answer is not to shame them into writing. The answer is to create a process where sharing knowledge feels safe, useful, recognised, and structured.

Technical authors and information managers should not ask, “Why won’t people write?”

They should ask:

“What is stopping people from sharing what they know, and how do we remove that friction?”

That is where documentation begins.

Why Technical Authors are disappearing from IT Projects

Technical authors are vanishing from many IT projects.

Project managers, hire a technical author
Hiring a suitable Technical Author

Not because documentation is no longer needed.

But because organisations convinced themselves that:

      • Agile removed the need for documentation
      • SMEs could “just write it”
      • Developers could document as they build
      • Wikis replaced structured information management
      • AI can now generate everything automatically

The result?

Documentation did not disappear. Ownership disappeared.

The Agile Misinterpretation

IT misunderstood Agile, believing it meant:

Less documentation.

What Agile challenged was:

      • Excessive bureaucracy
      • Huge unused specification sets
      • Documentation written for sign-off instead of operational value

But somewhere along the line, many organisations translated this into:

We no longer need technical authors.

So documentation responsibilities were fragmented across:

      • Developers
      • Business analysts
      • Product owners
      • Service managers
      • Support teams

Everyone became partially responsible.

Which usually means nobody became fully accountable.

IT Projects Still Produce Complexity

Modern IT environments are not simpler but more complex than they were 20 years ago.

Today’s projects involve:

      • Cloud platforms
      • APIs
      • Identity management
      • Cybersecurity controls
      • SaaS integrations
      • DevOps pipelines
      • Automation
      • Data governance
      • Compliance obligations
      • Hybrid infrastructure
      • AI systems

Yet many projects still assume documentation can “emerge naturally.”

What usually emerges is:

      • Scattered Confluence pages
      • Outdated SharePoint libraries
      • Tribal knowledge
      • Slack conversations acting as operational memory
      • Contradictory procedures
      • Uncontrolled revisions

Eventually, operational support inherits the chaos.

The “SMEs Will Write It” Fantasy

Subject Matter Experts are essential.

But SMEs are not usually:

      • Information architects
      • Editors
      • Audience analysts
      • Metadata specialists
      • Structured writing professionals
      • Governance specialists

Most SMEs focus on:

      • Delivering systems
      • Solving technical problems
      • Meeting deadlines

Documentation becomes secondary.

Postponed until the last phase of a project — when schedules collapse, and budgets tighten.

That is where technical authors historically added value:

      • Extracting knowledge
      • Structuring information
      • Standardising terminology
      • Identifying gaps
      • Challenging ambiguity
      • Creating usable operational guidance

Without that role, knowledge quality declines rapidly.

Documentation became Invisible Work.

In many IT organisations, documentation is now treated as:

      • Administrative overhead
      • Non-billable effort
      • A project afterthought
      • Something AI can “tidy up later”

Yet the same organisations later struggle with:

      • Failed handovers
      • Poor onboarding
      • Repeated incidents
      • Knowledge loss
      • Service desk dependency
      • Operational inconsistency
      • Audit failures

Because undocumented systems create operational drag.

The irony is simple:
The more complex IT becomes, the more valuable structured information becomes.

AI is speeding up the illusion

AI has amplified the belief that technical writing is “generating text.”

But experienced technical authors are not typists.

They managed:

      • Information quality
      • Knowledge structures
      • Content governance
      • Audience interpretation
      • Process consistency
      • Lifecycle control
      • Information retrieval
      • Operational usability

While AI can produce drafts quickly, it does not inherently:

      • Understand organisational risk
      • Detect conflicting operational procedures
      • Validate technical accuracy
      • Govern document lifecycles
      • Manage controlled information environments

Many times, AI speeds up the production of unmanaged content.

The Hidden Shift

Interestingly, technical authors have not entirely disappeared. We have changed titles:

Across IT projects, former technical authors now operate as:

      • Information managers
      • Knowledge managers
      • Content strategists
      • Service transition analysts
      • Governance specialists
      • Digital adoption consultants
      • Documentation engineers
      • Information architects

The writing component became only one part of a broader information role.

The Long-Term Risk

IT projects can survive in the short term without dedicated technical authors.

Until:

      • Key staff leave
      • Systems fail
      • Audits occur
      • Services scale
      • Migrations happen
      • Security incidents arise
      • Regulatory scrutiny increases

Then organisations rediscover the same truth:

      • Operational resilience depends on reliable information.
      • And reliable information rarely happens accidentally.
      • The disappearance of technical authors from IT projects may save money on a spreadsheet.
      • But over time, many organisations discover that they have not removed the need for technical authors.
      • They merely removed the people responsible for keeping organisational knowledge usable.

The Differences Among Writers: Roles, Responsibilities, and Skills

Companies need a better understanding of the roles, responsibilities, and skills needed for each writer. This knowledge enables them to identify the type of writer needed for tasks such as:

      • crafting captivating blog content,
      • producing technical documentation,
      • developing persuasive marketing copy,
      • designing user-friendly interfaces, or
      • creating winning bid proposals.

The Differences Among Writers: Roles, Responsibilities, and Skills Writers:

1. Content Writer

Responsibilities:

      • Writing articles, blog posts, and web content.
      • Researching to ensure accuracy and depth.
      • Optimising content for SEO.

Skills:

    • Strong writing and grammar skills.
    • Understanding of SEO principles.
    • Ability to write in various tones and styles.

2. Copywriter

Responsibilities:

    • Creating persuasive copy for advertisements, marketing materials, and product descriptions.
    • Developing slogans, taglines, and promotional content.
    • Collaborating with marketing and design teams.

Skills:

    • Excellent persuasive writing skills.
    • Creative thinking and idea generation.
    • Knowledge of marketing and advertising strategies.

3. Technical Writer

Responsibilities:

    • Writing manuals, user guides, and technical documentation.
    • Simplifying complex information for a non-technical audience.
    • Working with engineering and product teams to research information.

Skills:

    • Strong technical understanding and ability to learn new technologies.
    • Clear and concise writing style.
    • Attention to detail and organisational skills.

4. Grant Writer

Responsibilities:

    • Researching and identifying grant opportunities.
    • Writing proposals and applications to secure funding.
    • Communicating with funding organisations and stakeholders.

Skills:

    • Persuasive writing and storytelling.
    • Understanding of grant processes and requirements.
    • Intense research and organisational abilities.

5. Ghostwriter

Responsibilities:

    • Writing content on behalf of another person, often for books, articles, or speeches.
    • Mimicking the voice and style of the client.
    • Interviewing and research.

Skills:

    • Adaptability in writing style.
    • Discretion and ability to maintain confidentiality.
    • research and interviewing skills.

6. Scriptwriter (Screenwriter)

Responsibilities:

    • Writing scripts for films, TV shows, commercials, or video content.
    • Developing dialogues, characters, and plotlines.
    • Collaborating with directors and producers.

Skills:

    • Strong storytelling and dialogue writing.
    • Understanding of film and TV production processes.
    • Creativity and ability to develop compelling narratives.

7. Editor

Responsibilities:

    • Reviewing and revising content for clarity, grammar, and consistency.
    • Providing feedback and guidance to writers.
    • Ensuring content aligns with brand voice and guidelines.

Skills:

    • Excellent grammar and editing skills.
    • Attention to detail.
    • Strong understanding of writing styles and tones.

8. Journalist

Responsibilities:

    • Investigating and reporting news stories.
    • Interviewing and research.
    • Writing articles for newspapers, magazines, or online platforms.

Skills:

    • research and interviewing skills.
    • Ability to write under tight deadlines.
    • Objectivity and adherence to journalistic ethics.

9. Social Media Writer

Responsibilities:

    • Creating content for social media platforms.
    • Developing engaging posts, captions, and multimedia content.
    • Analysing social media metrics and adjusting strategies.

Skills:

    • Understanding of social media trends and platforms.
    • Creative and concise writing.
    • Ability to engage and interact with an audience.

10. Content Strategist

Responsibilities:

    • Developing content plans and strategies to meet business goals.
    • Coordinating with writers, designers, and marketers.
    • Analysing content performance and optimising strategies.

Skills:

    • Strategic thinking and planning.
    • Understanding of content marketing and SEO.
    • Strong project management skills.

11. UX Writer

Responsibilities:

    • Creating user-friendly copy for websites, apps, and other digital products.
    • Writing microcopy, such as buttons, error messages, and tooltips.
    • Collaborating with designers, product managers, and developers.

Skills:

    • Understanding of user experience (UX) principles.
    • Ability to write concise and clear copy.
    • Experience with user research and testing.

12. UX Strategist

Responsibilities:

    • Developing UX strategies to enhance user satisfaction.
    • Conducting user research and analysing data.
    • Working with cross-functional teams to implement UX improvements.

Skills:

    • Strong understanding of UX design and principles.
    • Analytical and research skills.
    • Ability to develop and communicate strategic plans.

13. Bid Writer

Responsibilities:

    • Writing proposals and bid documents for contracts and projects.
    • Ensuring compliance with bid requirements and guidelines.
    • Collaborating with sales, finance, and technical teams.

Skills:

    • Persuasive writing and attention to detail.
    • Understanding of bid processes and regulations.
    • Strong organisational and project management abilities.

Technical Author | learn how to project manage documentation projects

As a technical author expert, I recommend that other technical authors should learn how to plan their documentation projects. One of the most common issues project managers face is underestimating the complexity of documentation projects. This can have negative consequences on the project’s success, as inadequate timelines and impossible targets can be set without consulting professionals for advice.

Tweet
Pin
Share
0 Shares

Technical authors, give your career a shot in the arm. Learn how to plan documentation projects effectively to project manage effectively. Project managers often underestimate the challenges of projects that involve documentation. This leads to limited success because of unrealistic timelines and targets.

I know the process behind the production of multiple documents. Proper project management is crucial, especially when managing complex documentation tasks. While prioritising other aspects of the project over documentation, they fail to ask a professional for their input and guidance. When the technical author(s) arrive and look at the list of documents and the PM timelines, let’s say you can hear our sighs.

We need clear communications if the PM expects to deliver the entire project. How do you manage 60 + documents? How long does it take to write one document? Have it reviewed, but remember that the document might be out of date further along with the project. Clear communication with stakeholders and team members involved in the writing stages is paramount. The project manager must understand the expectations of the technical author(s) they will work with and must effectively project manage to meet those expectations.

Project plans may face issues when updates require time-consuming document review and revision phases. Thus, managing the project efficiently becomes critical.

Project managers and technical writers can work together to succeed on big documentation projects. However, a technical author to lead might be a better idea and offer better results.

From Contract to Permanent

my transition from contractor to perm

Tweet
Pin
Share
0 Shares

In 2004, while facing redundancy for the third time, I accepted a six-month contract with BT to fill a potential gap until a permanent role became available. A former colleague told me that contracting can be a long-term career choice. He offered various reasons, but I went ahead; I couldn’t afford to be out of work.

trnsition from contract to perm

My first two contracts were with BT in London and at its HQ in Ipswich. Then came T-Mobile (now EE), NTTE, and Capita. Before I knew it, five years had passed, and recruitment agents were calling with contract and permanent job opportunities. 

However, some agents were reluctant to forward a contractor to a client wanting a permanent technical author. Recruitment agents had stories of contractors accepting a permanent role and quitting after a month (or a week) to return to the contract market. Yet, while I interviewed for several permanent positions, none matched what I wanted.

I moved between tasks, meeting TAs who shared work stories each year. 

Note: To be a technical author, you need a sense of humour and a sharp wit.

However, I never got to grips with the gaps between contracts. While the money was above average, it allowed me to pay myself an inconsistent amount every month. During the 2008 financial crisis, my earnings dropped by a massive 33%, which was further exacerbated by a four-month contract gap. During that period, BlackBerry offered me a permanent role. Unfortunately, I didn’t stay long because of an overzealous  Canadian-based micro-management team leader. So desperate to make her mark, she called me as soon as she arrived at her office in Waterloo, Ontario. She said during one call, I must learn to manage my stress. Yet, she caused me stress by constantly interfering and telling me how to do my job—her two years of experience against my 13 years.

Yet, look on the bright side: with more contracts under my belt, I developed more skills: 

  • SharePoint (Document Management)
  • Confluence
  • Help Desk support, transition from contractor to perm
  • policy & process writing, 
  • VISIO process flows
  • ITIL (incident and change management), 
  • ITSM. 
  • PCI/DSS, 
  • ISO 27001 Audits and 
  • operations manuals for data centre migrations and
  • project management

Goodbye to software environments and hello to the broader world of technical authoring. Not only did I broaden my experience, but I also travelled to Pune in India, as well as to Germany, Belgium, and Canada. 

I have started, but cannot finish.

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

A common trend with contracts is poor budget allocation. In one PCI/DSS project, I worked with two technical authors on a 10-week assignment. By then, the PM had used most of the budget to prepare for an audit by hiring an expensive external consultant.

We needed to prepare the groundwork, identify SMEs, and divide the sixty titles between us. After five weeks, we began speaking with SMEs and drafting the documents. The task exceeded our capabilities; it involved a great deal of labour and an inadequate duration. Although the company in question went bankrupt during the pandemic, it had no connection to the project. 

Hiring managers and project managers often struggle with the dynamics of documentation projects. Many project managers assume that documentation is a straightforward task. It rarely works out that way.

On my journey to a permanent role, the points below formed the basis of my decision. If you are a contractor considering a change towards a permanent position, consider what you could offer as a permanent employee.

  • I could concentrate on doing what I’m good at rather than spending gaps and seeking new freelance jobs.
  • Working as a freelancer has allowed me to improve my flexibility and adapt to new situations. Technical authors require an understanding of adaptability, as well as the capacity to operate effectively individually or within group settings. 
  • I respond to many people, environments, and attitudes. This experience has enabled me to work effectively with diverse management styles and personalities.
  • Can they manage me? Even as a freelancer, my role is to contribute to a team. And as a freelancer, I have always been “managed…” by my clients.
  • How would you benefit our clients? If you would like me to be involved in client contact, I can assist with their needs, leveraging my knowledge and experience to provide effective documentation solutions. 

We are also

    • I am confident that our considerable Skill Set will shine through.
    • Understand the issues and be prepared to address them head-on. 
    • experience of multiple environments
    • recognition of common problems
    • Understanding of project needs
    • broad experience
    • Renewed enjoyment of teamwork

What are you thinking? 

Perhaps you’re wondering, how can I transition from contract to permanent and take a significant financial hit? As a contractor, my earnings fluctuated, with no consistent monthly payments due to:

    • The time between contracts is a few weeks to a couple of months.  
    • Increasing administration and overheads through my limited company. 
        • unemployment insurance (£150 per month to cover me in case of an injury or debilitating illness),
        • personal and public liability insurance (£10m in value £160 p/a), 
        • private medical for quick treatment (£1200 p/a)
        • accounting fees (£1200+ p/a)
        • Travel costs were deductible. 
          • Car mileage
          • Air Fares between Brussels and Gatwick
          • Hotels and meals while working away from home in the UK
    • Increased Taxation on Dividends
    • The Government fails to grasp that risk-takers often lack holiday pay, sickness benefits, and company benefits.

Before the pandemic, I received about five calls a week from agents checking my availability for work. Meanwhile, I maintained a growing Excel spreadsheet of calls, listing potential clients, and updated my CV every six months.

During the 2020 pandemic, I was out of work from March to October. My company’s accounts for 2020 showed a £ 5,000 loss, and a £ 3,000 loss in 2021.

In April 2021, to circumvent IR35, I joined an umbrella organisation.

Post-pandemic, IR35 has played havoc with the contract market, causing an enormous drop in calls from recruitment agents. 

Here's a fun fact. In eighteen years as a contractor, I worked at 45 different companies. That doesn't include about ten companies where I walked away after a few days to avoid a disaster in the making.

Why did I walk?

The hiring manager sold me a dud while management expectations were unrealistic..

Between 2004 to 2021 over 300 hiring managers received my CV and more than half interviewed me.

The last journey

In 2021/22, after I completed a long-term contract project, I focused on finding a permanent role. The HR department of a County Durham-based bank (my home county) offered me an interview. However, HR rejected me because of my contracting background. So, if you are reading this, take note. I am now a permie, see what you missed. 

transition from contracting to perm

While I had three more interviews, the sticking point was the salary. A business owner, a lady, contacted me after finding my CV online and offered me a permanent role paying £ 35,000 after a five-minute discussion.

And Finally…

So, when I read the Atkins job description, I thought, let’s give it a go, with nothing to lose. During the interview, the interviewer asked the inevitable question. I refer the reader to the first three paragraphs of this post. 

After quitting the contract market, I am no worse off when considering my salary and the benefits I receive. I no longer worry about tax bills, dividend taxes, accounting fees, and various insurance costs that can be a fortune. A permanent role has worked for me and might work for you. Never say never.

Technical Authors what we are and what we are not

Unveiling the True Potential of Technical Authors: More Than Just Writers

Don’t let the title of Technical Author fool you. Regardless of your opinion, do not underestimate us. We have the potential to offer unexpected help in more ways than one. Allow me to dispel the myth regarding our identity.

Misconceptions About Technical Authors

Not Just Software Developers

If I had proficiency in BASIC, C/C++, Java, etc., I would earn significantly more as a developer. While I receive calls for API documentation, a skill requiring familiarity with code, my primary focus remains on creating clear and concise technical documents.

Not Project Managers

I am not a project manager certified through Prince2, Agile Scrum, or similar programs. My project management skills are specific to technical documentation, where I manage schedules and meetings with subject matter experts (SMEs) and other stakeholders. My role does not include:

  • Detailed project planning, progress evaluation, risk management, or issue resolution. For these tasks, a full-time project manager is essential.
  • Secretarial duties such as organising colleagues’ schedules or taking minutes. I record my meetings and extract the relevant information for documentation purposes.

Not Departmental Experts

While familiar with the terminology, I am not an expert in every department. I learn on the job, facilitating communication and collaboration through practical verbal and written skills. My goal is to support and encourage achieving organisational goals without making the process daunting.

The True Role of a Technical Author

An External Consultant with a Plan

As an external consultant, I often use the MoSCoW method to categorise initiatives into must-haves, should-haves, could-haves, and will-not-haves (or wishful thinking). This approach ensures a structured and prioritised documentation process.

Documentation Management

Upon joining, I sift through all available documentation to identify gaps and areas for improvement. I manage documents and content using tools like SharePoint and Confluence, ensuring efficient information management for your teams.

Project Management Skills in Context

My project management skills, while not as extensive as those of a certified project manager, include:

  • Designing new templates and improving the structure of existing documents.
  • Documenting processes across several categories and arranging meetings with SMEs.
  • Planning, writing, reviewing, publishing, and maintaining content using tried and tested methods.

Extensive Experience and Resourcefulness

With over 23 years of experience, I possess an extensive library of generic documentation and various templates. This resourcefulness lets me tweak documents to meet your business profile, saving time and money.

ITIL and ITSM Expertise

I have experience producing IT Service Management (ITSM) documents based on ITIL best practices, including:

  • Service Design, Service Transition, Service Operation, and Continual Service Improvement.
  • Delivery and Service Support, Availability, Capacity, and IT Service Continuity Management.
  • Incident, Problem, Change, Release, Configuration Management, and Service Desk documentation.
  • Policy, Process & Standards documentation for ISO27001/9001 compliance, GDPR, PCI/DSS, and security projects.
  • Disaster recovery scenario documentation.
  • Infrastructure documentation to support large-scale networks and recently migrated infrastructures.

Editing and Enhancing Existing Content

I can enhance existing content by adding VISIO drawings, new screenshots, rewording policies, adding narratives, and creating new templates. I am also skilled at ensuring consistency and structure in Word documents.

Tools and Techniques

I keep projects on track using spreadsheets, MS Word, PowerPoint, and VISIO. I also suggest ways to maintain up-to-date and current documentation, treating information as an invaluable asset.

SharePoint and Confluence Management

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

If you lack a documentation strategy, I can create a plan tailored to your needs. Proper management includes ensuring documentation is available to all staff, appropriately updated, rewritten, and archived. Ownership, version control, and historical control are critical aspects of effective

documentation management.

Key Benefits of Effective Technical Documentation

Implementing adequate technical documentation can lead to the following:

  • Reduced costs.
  • A more responsive help desk/support system.
  • Better-informed staff and confidence in performing procedures.

By recognising the true potential of Technical Authors, organisations can leverage their skills to achieve greater efficiency, clarity, and overall

success.

Get a head start

Templates with generic content

Do you have a documentation project lurking in the background and you are yet to get to grips with the detail? I have available many templates which contain generic policies, processes, and standards content relating to the following documentation:

      • PCI/DSS
      • ISO27001
      • ITIL
      • ITSM

If you are embarking on a project for any of the above from scratch, you can save time measuring into months by using the relevant template.

Consider the fact it can take upwards of six weeks to produce one document of between 20 to 30 pages, imagine the scale of the work if you have more than sixty titles to write from scratch.

The content within the documents will require tweaking to make them relevant to your company, such as Team names and Team members, Technical terms and branding.

However, be aware I do not own a comprehensive list of Policy and Process documents. My library covers the documents that will take time to produce.

VISIOs

I own VISIO drawings covering the following and many more:

      • Incident management
      • Change management
      • Problem management
      • Document lifecycle

Templates with Headings only

You may require a set of pre-headed templates to help you document your Network. You can use these templates to document your servers and use the documents for many purposes.

Training: help new starters gain knowledge about the Network.

Audit: Have to hand information that can help you manage your Network over the long term.

Data Centres: Use the templates to plan a data centre migration.

      • Operating documents
      • Installation guides
      • Profile documents (5-Pages)

Process, Procedure, Work Instruction, Plan, Strategy and Standards — Know the Difference

Clear documentation depends on understanding the difference between processes, procedures, work instructions, plans, strategies and standards. This article explains how each fits into a structured documentation framework.

Tweet
Pin1
Share
1 Shares

Many organisations use the terms process, procedure, work instruction, plan, and strategy interchangeably. They are not the same. This article explains the key points to help clarify these differences.

Confusion between these terms leads to poor documentation, unclear responsibilities, and inconsistent delivery.

If you work in technical authoring, information management, or governance, understanding the difference is essential.

A good documentation framework clearly separates these elements and ensures people know what they must do and why.

What is a process?

A process is a set of interrelated activities that turn inputs into outputs.

A process describes a complete business activity from beginning to end.

You must:

      • Learn the process
      • Understand why it exists
      • Perform it end-to-end

A process is:

      • A high-level description of work
      • Cross-functional
      • Ongoing and repeatable
      • Updated periodically
      • Supported by policies and standards

A process answers the question:

“How does the business operate?”

What is a procedure?

A procedure provides more detail than a process but less detail than a work instruction.

It explains how to perform sequential tasks to achieve a defined outcome.

A procedure usually:

      • Follows a logical sequence
      • Has an obvious start and finish
      • Can be completed in one working session
      • Describes responsibilities

A procedure answers:

“How do we complete this activity?”

What are work instructions?

Work Instructions (WI) describe exactly how to perform a specific task.

They provide step-by-step guidance with no ambiguity.

A work instruction:

      • Describes one task
      • Contains detailed steps
      • May include screenshots or diagrams
      • Removes interpretation

Work instructions answer:

“How do I do this task?”

What is a plan?

A plan is not a process.

Many organisations confuse the two.

A management plan describes what will be done, not how work is performed.

A plan typically includes:

    • Objectives
    • Resource allocation
    • Timescales
    • Responsibilities
    • Risk considerations
    • Contingencies

A plan shows how an organisation will move from Point A to Point B.

It supports the strategy by describing how resources will achieve the aim.

A plan answers:

“What are we going to do?”

What is a strategy?

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

It defines direction rather than detailed actions.

A strategy typically includes:

      • Current position (Point A)
      • Desired position (Point B)
      • Problems and constraints
      • Opportunities
      • Tools and approaches
      • Decision principles

A strategy considers obstacles and risks that may slow progress.

Strategy answers:

“Where are we going and why?”

Your strategy defines what you want to achieve.

Understanding the difference between a strategy and a plan allows organisations to make better decisions.

What is a standard?

Standards define mandatory rules and behaviours.

They support policies and ensure consistency across the organisation.

Standards are:

      • Mandatory
      • Enforceable
      • Organisation-wide
      • Consistent
      • Long-term

Define expected behaviour, for example:

      • Email signatures
      • Naming conventions
      • Approved hardware and software
      • Document templates
      • Security controls

Must be enforced to be effective.

This applies equally to policies and standards.

Why does this matter?

When organisations confuse these terms, documentation becomes chaotic:

      • Plans get mistaken for processes
      • Procedures become incomplete
      • Work instructions disappear
      • Strategies become wishlists
      • Standards are ignored
      • Clear documentation separates these layers and ensures:
      • Consistent delivery
      • Clear responsibilities
      • Better governance
      • Easier audits
      • Stronger information management

This structure is the foundation of a well-run documentation system.

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.