Category: Documentation

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 Most Information Management Systems Fail?

Most information management systems do not fail because of the technology. They fail because organisations place the wrong people in charge of them.

It might sound tough, but I’ve seen the same issues over and over in documentation, governance, migration, and digital transformation projects for years.

A company buys a shiny new platform. Perhaps it is SharePoint, Asite, OpenText, Confluence, or some other enterprise repository promising collaboration, governance, and a “single source of truth.” Senior management signs off on the budget. Consultants arrive. Workshops take place. PowerPoint slides appear with words like transformation, efficiency, and digitisation.

Then reality arrives.

The people tasked with implementing the system often do not understand:

      • Information architecture
      • Metadata strategy
      • Document lifecycle management
      • Governance
      • Retention
      • Taxonomy
      • Search behaviour
      • Classification
      • User behaviour
      • Migration risk
      • Audit requirements

Instead, the responsibility falls to:

      • Project managers are trying to keep timelines alive
      • Administrators are learning the system as they go
      • Engineers or operational staff are given “document duties”
      • Junior analysts following configuration guides
      • Contractors brought in late with no authority
      • Teams follow instructions without understanding why the rules exist

The result is predictable.

Folders become dumping grounds. Metadata becomes inconsistent. Naming conventions collapse within months. Nobody owns review cycles. Duplicate files spread everywhere. Obsolete documents survive for years. Search becomes unreliable. Staff stop trusting the repository and return to shared drives, desktops, Teams chats, and email attachments.

The system technically works.
The information ecosystem does not.

One of the biggest problems is the culture of “learning on the job” without experienced guidance. There is nothing wrong with learning. Every profession requires it. The danger appears when organisations assume complex information governance can be improvised by whoever is available.

Information management is not merely administration.
It is a discipline.

A proper information manager understands:

      • Governance structures
      • Risk
      • Regulatory obligations
      • User behaviour
      • Retrieval logic
      • Version control
      • Controlled publishing
      • Retention schedules
      • Audit defensibility
      • Migration integrity
      • Operational continuity

Without that knowledge, teams often follow instructions mechanically.

“Upload the files.”

“Apply metadata.”

“Move everything into SharePoint.”

“Create the folders.”

“Archive old material.”

But few stop to ask:

      • Why are we storing this?
      • Who owns it?
      • Who reviews it?
      • Is it duplicated elsewhere?
      • Is it authoritative?
      • What is the retention requirement?
      • What business process depends on this information?
      • What happens if somebody follows the wrong version?

That lack of understanding is where many systems quietly begin to decay.

The harsh truth is that some organisations confuse software knowledge with information management expertise. Knowing how to create a SharePoint library does not make someone an Information Manager, just as knowing how to use Word does not make someone a technical author.

Technology alone cannot compensate for weak governance.

Another recurring issue is leadership detachment. Senior management often sees Information Management as an IT deployment rather than an operational control mechanism. Once the platform is installed, they assume the job is complete.

It is not.

The difficult work starts afterwards:

      • Governance
      • Ownership
      • Review enforcement
      • Classification
      • Rationalisation
      • Training
      • Audit checks
      • Lifecycle management
      • Repository discipline

Without these controls, entropy takes over.

This is why many migrations fail to improve anything. Organisations transfer chaos from one platform to another. The old shared drive becomes a badly organised SharePoint site. The same ROT — redundant, obsolete, and trivial information — survives the migration untouched.

A poorly governed system can often outperform an excellent platform without it.

The uncomfortable conclusion is this:

Most information management failures are not technical failures.
They are failures of leadership, governance, experience, and understanding.

Until organisations place experienced people in charge of their information estates — people who understand both systems and governance — many so-called digital transformations will continue to become expensive storage exercises disguised as progress.

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 Hidden Cost of Cutting Your Technical Author

The Hidden Cost of Cutting Your Technical Author

When budgets shrink, technical authors and documentation teams are often the first to be cut. It’s easy to justify — “We already have the templates.”
But removing or not replacing your technical author rarely saves money. It hides the cost until it explodes.

1. Knowledge Loss

A technical writer understands how different parts of documentation fit together.
When they leave:

      • Knowledge silos collapse.
      • People work from outdated copies.
      • Time is wasted rediscovering old lessons.

The cost of confusion soon outweighs the saved salary when a technical author is missing.

2. Compliance and Audit Risk

Accurate documentation underpins certifications such as ISO 9001, ISO 27001, PCI DSS, GDPR, and ITIL.
When documents are out of date or mislabelled:

      • Audit evidence disappears.
      • Nonconformities multiply.
      • Certification renewals become a gamble.

Even one mismatched title or missing version record can result in audit failure. Without the oversight of a technical author, these issues are more likely to occur.

3. Operational Inefficiency

Without a technical author:

      • Everyone edits documents their own way.
      • Version control collapses.
      • People spend hours searching instead of producing.

It’s not efficiency — it’s chaos disguised as productivity. A skilled technical author maintains order.

4. Loss of Professional Polish

Documentation is a reflection of your organisation’s competence. When quality drops:

      • Clients notice inconsistent tone and structure.
      • Reports lose credibility.
      • Your brand looks disorganised.

A technical author provides the invisible glue that holds professional standards together.

5. Increased Risk and Cost

When no one owns the documentation:

      • Processes contradict each other.
      • Projects lose traceability.
      • Clients misinterpret requirements.

Eventually, you’ll hire a contractor to rebuild the documentation ecosystem — and pay three times what you “saved.” A technical author prevents these costly mistakes.

6. Demoralised Teams

Without a dedicated author:

      • Engineers are forced to write in their spare time.
      • Quality suffers because writing is not their priority.
      • Ownership disappears — and so does accountability.

Documentation becomes everyone’s side job and nobody’s responsibility. Here, a technical author provides much-needed oversight.

⚙️ In Summary

Short-Term Thinking Long-Term Reality
“We’ll save a salary.” You’ll pay three times more later to fix it.
“Anyone can write.” Not everyone can structure or govern documents.
“We have templates.” Templates without governance are worthless.
“We’ll update later.” “Later” becomes “never” — and non-compliance follows.

My Final Thought

Removing your technical author isn’t cost-saving. It’s cost-shifting.
You’re trading short-term budget relief for long-term operational debt. The moment a compliance audit or client review exposes the cracks, the real bill arrives

When Document Titles Don’t Match Their Content: A Hidden ISO 27001 Audit Risk

In my career I have worked on several contracts correcting documents that failed an ISO27001 audit. I found several change management process documents that were anything but processes. They were plans with a workflow diagram, but the main part of the text explained the planning, not the exact steps.

This mismatch between title and content can undermine an ISO 27001 audit. Users and auditors will struggle if document names don’t match the content, leading to wasted time and a lack of trust in the documentation.

Why It Matters?

ISO 27001 requires documentation to be consistent, accurate, and traceable. Under Clause 7.5, all documented information must be suitable and adequate for its purpose.
If your titles mislead the reader — for instance, labelling a plan as a process — it fails that requirement outright.

Auditors don’t just check boxes; they follow document trails. Incorrectly named or categorised documents suggest your information management and document control are weak. That can lead to a nonconformity finding and a costly re-audit.

The Domino Effect of Wrong Titles

Incorrectly titled documents have consequences beyond compliance:

      • Search confusion: Teams waste time locating or referencing the wrong document.
      • Duplicated effort: Multiple people recreate or update files that already exist, under a different name.
      • Loss of trust: Users stop relying on the repository, assuming it’s unreliable.
      • Audit remediation time: Technical authors must spend months re-titling, rewriting, and re-validating content.

Every mis-titled document represents avoidable technical debt that eventually needs to be paid back — usually as long, tedious remediation work.

The Cost of Inaccuracy

In one project, we discovered over 200 documents whose titles didn’t match their content. Entire categories had to be re-audited, cross-referenced, and reissued.
The team lost weeks, and the company risked missing its ISO 27001 renewal.

This wasn’t a writing issue — it was a metadata and document control failure. Titles, categories, and filenames are all metadata fields that auditors use to navigate your Information Security Management System (ISMS). When those don’t align, your ISMS fails to demonstrate control.

How to Get It Right

  1. Align title and intent
      • If it’s a process, describe repeatable steps.
      • If it’s a plan, define scope, actions, and timelines.
  1. Use controlled metadata
      • Add document owner, version, and approval date.
      • Classify documents by type and purpose.
  1. Include a clear scope statement
      • A single line beneath the title explaining purpose helps readers instantly understand what they’re reading.
  1. Review your taxonomy
      • Periodically audit your repository to ensure naming conventions still reflect actual content.
  1. Engage technical authors early
      • They can design taxonomies, enforce naming conventions, and prevent this issue before it becomes a compliance risk.

Final Thought

A wrong title might not seem serious — until an auditor can’t find what they’re looking for.
When document names and content don’t align, it’s more than a clerical error; it’s a failure of document control.

Accurate titling and classification aren’t just about neatness — they’re a sign that your organisation takes information management, and ISO 27001 compliance, seriously.

If your document library has grown organically over the years, now’s the time to review it.
A few days of focused taxonomy work today can save months of painful remediation tomorrow.

Author Bio:
Michael Clark is a Senior Technical Author and Information Management Specialist at AtkinsRealis, with extensive experience in documentation strategy, metadata design, and ISO 27001 compliance. He writes about documentation standards, information governance, and practical approaches to managing technical content across large organisations.

Using Your Technical Authors as Strategists, Planners, and Consultants

Many businesses still misunderstand what a technical author can deliver.
They see a writer — not a strategist. A formatter, not a planner. A proofreader — not a consultant.

When used correctly, technical authors bring structure, compliance, and clarity to every stage of the information lifecycle. They turn documentation into a strategic enabler that supports ISO certification, ITSM frameworks, and information governance.

I didn’t gain this experience by taking on low-level contracts.
I built it by accepting complex, high-expectation assignments that demanded expertise — not routine.
Projects governed by ISO 27001, ISO 9001, PCI DSS, GDPR, and ITIL-aligned IT Service Management (ITSM) systems, where documentation wasn’t an afterthought, but a control in its own right.

From Document Writer to Information Strategist

Early in my career, I learned that a procedure is only as good as the system it supports.
As I advanced, I began designing those systems — integrating documentation with SharePoint, Asite, and enterprise knowledge bases to create traceable, auditable, and user-friendly environments.

That shift — from producing documents to architecting knowledge — is what separates an average writer from a documentation strategist.

Embedding ISO and Regulatory Frameworks

ISO 9001 — Quality Management

ISO 9001 demands consistency, clarity, and control. Technical authors design document templates, review workflows, and approval paths that prove process reliability. Well-structured documentation becomes part of the organisation’s quality evidence during internal and external audits.

ISO 27001 — Information Security

Under ISO 27001, documentation itself is a security control. Policies, risk registers, and incident procedures must align with the ISMS.
Experienced authors ensure classification, access permissions, and audit records are built into the documentation framework, not bolted on afterwards.

PCI DSS — Payment Card Security

PCI DSS requires clear operational documentation to evidence data protection. Authors provide traceable, reviewed, and controlled documents that survive audit scrutiny and demonstrate compliance with strict data-handling protocols.

GDPR — Data Protection and Privacy

GDPR compliance relies on transparency and accountability. Technical authors transform complex regulation into usable, plain-English policies: data-retention schedules, subject-access request processes, and breach-notification guides that staff can actually understand and apply.

Aligning Documentation with ITIL and ITSM

In IT environments, documentation underpins every ITIL and IT Service Management process:

      • Incident Management: Documenting escalation paths and resolution steps for service continuity.
      • Change Management: Recording change requests, approvals, and rollback plans to ensure traceability.
      • Problem Management: Capturing known errors and lessons learned to improve service quality.
      • Configuration & Asset Management: Maintaining controlled, versioned records of infrastructure and applications.
      • Service Continuity: Creating and maintaining recovery and resilience documentation aligned with ISO 22301.

A technical author versed in ITIL ensures that every process has the appropriate governance and documentation frameworks to meet compliance, audit, and service-delivery standards.

Aligning with Information Management and Document Control

Technical authors sit at the crossroads of Information Management (IM) and Document Control (DC) — translating policies into practice and ensuring that every piece of information has purpose, ownership, and lifecycle control.

      • In Information Management, authors define how data becomes information — creating naming conventions, metadata structures, taxonomies, and templates that keep repositories usable and compliant.
      • In Document Control, they understand versioning, approval hierarchies, baselining, and retention schedules — the mechanisms that give documentation its legal and operational validity.
      • Together, these functions ensure that knowledge doesn’t just exist, but is managed, retrievable, and auditable across departments, projects, and systems.

Where Information Management provides governance and Document Control enforces consistency, technical authors provide the structure and clarity that make both work.

The Modern Technical Author’s Toolkit

Today’s senior technical author is:

      • A strategist, aligning documentation with ISO, GDPR, ITIL, and corporate frameworks.
      • A planner, integrating documentation into project and service lifecycles.
      • A consultant, advising leadership on governance, information management, and document control.
      • A knowledge manager, ensuring content remains accurate, traceable, and secure.
      • A systems designer, configuring SharePoint or Asite to automate metadata, version control, and review cycles.

When you position your technical authors at this level, you gain more than documentation — you gain information assurance.

Experience Earned Through Expertise

Every project I’ve worked on — from ISO 9001 audits to 27001 ISMS documentation, from GDPR compliance to ITIL process alignment — has reinforced one truth:
Documentation is infrastructure.

It connects people, process, and technology.
It demonstrates governance and compliance.
And when managed properly, it becomes the backbone of every successful audit and transformation.

Final Thought

Technical authors who have grown through challenging environments understand how documentation supports the wider information ecosystem — policy, process, system, and control.

They close the gaps between communication and compliance, between information and evidence.

So before assigning your technical authors to “tidy up templates,” ask instead:

“Can this person help us align ISO, ITIL, and Information Management requirements into a single, coherent documentation strategy?”

If the answer is yes, you’re not hiring a writer.
You’re engaging a strategic partner in governance, compliance, and service excellence.

Why do managers struggle to understand their Technical Authors?

A common challenge for tech writers like me is that their managers often do not fully understand our roles. When managers underestimate our abilities, things are easier for them, but challenging for us.

Based on my experience, managers often overlook

    • the critical contribution of documentation to risk reduction, compliance, and operational efficiency.
    • Producing documentation requires significant effort.
    • The cross-functional nature of our work can create confusion about team assignments. Say we have change management experience in the creation of flows and narratives. It led to a placement in business change where we possess the knowledge but not the expertise.
  • Difficulty in Justifying ROI to Clients
      • Clients see documentation as a “nice-to-have” rather than a must-have—until something goes wrong (e.g., legal disputes, compliance failures).

Managers struggle to understand how documentation:

      • Reduces support costs (fewer customer complaints)
      • Ensures compliance (avoids regulatory penalties)
      • Speeds up onboarding (reduces training costs

The misconception that AI or SMEs can replace us by writing documentation, or that AI tools can auto-generate content. Small businesses often don’t have technical writing skills, and AI content needs a person to check it for correctness, meaning, and how easy it is to use.

How can we address these challenges?

  1. Educate Managers on the Value of Documentation
        • Show real-world cost savings (e.g., reduced rework, fewer customer complaints).
        • Highlight case studies where poor documentation caused project delays or legal risks.
    2. Push for Strategic Placement in the Organisation
      • Place this under Quality, Knowledge Management, or Digital Strategy (if it helps the business).
      • Position documentation as a core business function, not as an afterthought.

3. Demonstrate Our Expertise Beyond Writing

      • Emphasise our role in governance, process improvement, content structuring, and compliance.
      • Showcase technical authors as information architects rather than just writers.

Interested in a proposal to improve how your organisation uses technical authors? Ask me?

Technical Author: How Simple or Easy Is our job?

Let’s start with a question: what skills are essential for excelling in a technical author job?

      1. How many of you have technical authors on your team but do not know what they do?
      2. Have you tried to fit them in somewhere, or wanted to find them a role and failed?
      3. Have you written technical documentation for a client? If so, how did it go?

You may have given up trying to understand their role, thinking you should upskill them to meet your priorities. You might not grasp what technical authors contribute in their jobs and underestimate their potential.

Let’s examine the issue.

Managers often perceive technical authoring as “writing documents.” However, in reality, it is a complex, multidisciplinary role that requires expertise in several areas. One important area is understanding the technical author’s job in depth:

Understanding Technical Information

Technical authors translate complex concepts into clear, user-friendly documentation that is easy to understand. They engage with Subject Matter Experts (SMEs), interpret complex jargon, and ensure the accuracy of the information presented.

Structuring and Standardising Content

They do more than write. Technical writers need to work with formatting, templates, metadata, and indexing, which makes their job complex.

Managing Multiple Stakeholders and Reviews  

Technical authors liaise with stakeholders and end users, each with different priorities and expectations.

The process involves multiple reviews by experts, who underestimate the work required to improve the documents. This aspect is a key part of their jobs.

Adapting to Evolving Tools and Technologies  

From document management systems (DMS) like SharePoint, Confluence, and Asite to API documentation tools, technical authors must stay up-to-date with the constantly evolving industry standards. AI and automation are changing the nature of jobs and making technical writing more complex.

Balancing Quality with Deadlines  

Managers don’t always prioritise documentation, which means writers have to finish it quickly, but still produce great work.

They must work within strict project deadlines while ensuring accuracy, compliance, and usability. These demands highlight the challenges inherent in a technical author’s job.

Why do managers struggle with technical authors and their role? Let me know in the comments.

How to Create or Update Policy and Process Documentation

Discover how to plan, draft, and publish policies and processes that improve workflows, meet compliance, and support your organisation

Tweet
Pin
Share
0 Shares

Creating or updating policy and process documentation can feel daunting. By using the proper methods, you can make documents that are easy to read, useful, and compliant with regulations, assisting with daily work.

This guide shows you how to plan, write, and publish policies and processes, including schedules, resources, and necessary skills.

Step 1: Define the Scope and Plan

Key considerations:

    • Objectives: Are you meeting compliance, improving workflows, or clarifying roles?
    • Stakeholders: Engage department heads, compliance teams, and end users early.
    • Scope: Decide which policies and processes to create or update, prioritising business-critical areas.
    • Audit: Review existing documents for gaps, outdated content, or duplicates.

Estimated time:

    • Project planning: 1–2 weeks
    • Documentation audit: 2–4 weeks

Step 2: Research and Gather Data

Key considerations:

    • Compliance: Align with regulations and standards.
    • End users: Understand how staff will use the documentation.
    • Current practices: Observe workflows and interview subject matter experts (SMEs).
    • Technology: Ensure compatibility with tools such as Asite DMS or SharePoint.
    • Estimated time:
    • Research and interviews: 4–8 weeks
    • Process observation: 2–6 weeks

Step 3: Draft Policies and Processes

Key considerations:

    • Structure: Include purpose, scope, responsibilities, and procedures.
    • Clarity: Write in plain English. Avoid jargon unless necessary.
    • Visuals: Use workflow diagrams (e.g., Visio) for complex processes.
    • Version control: Track changes and manage document versions.
    • Estimated time:
    • Simple policy: 2–4 hours per document
    • Complex policy: 2–3 days with SME review
    • Process mapping: 3–7 days

Step 4: Review and Validate

Key considerations:

    • SME review: Check accuracy and compliance.
    • Testing: Pilot with a sample group of users.
    • Refinement: Incorporate feedback and re-draft as needed.
    • Estimated time:
    • Review cycle: 1–2 weeks per draft
    • Pilot testing: 2–4 weeks

Step 5: Finalise and Publish

    • Key considerations:
    • Approval: Secure sign-off from leadership.
    • Formats: Publish in user-friendly formats (PDF, intranet, or DMS).
    • Training: Provide user guides or training sessions to support adoption.
    • Estimated time:
    • Formatting and approval: 1–2 weeks
    • Training materials: 2–4 weeks

Project Timelines

    • New documentation: 3–6 months (medium complexity)
    • Updating documentation: 2–4 months

Resources Needed

    • Technical authors: Skilled in plain English writing and structuring documents
    • SMEs: Knowledgeable in compliance, operations, and workflows
    • Tools: Document management systems (Asite, SharePoint) and process mapping tools (Visio)
    • Reviewers: Stakeholders to provide input and approvals
    • Training resources: Guides and sessions to drive adoption

Expertise Required

    • Writing and editing skills
    • Interview techniques to gather SME knowledge
    • Regulatory and compliance awareness
    • Process mapping and visualisation
    • Change management experience

Final Thoughts

Policy and process documentation reduces risk, improves efficiency, and ensures compliance. By following these steps—plan, research, draft, review, and publish—you can create documentation that staff will actually use and trust.

 

Navigating the Jungle of Contracting: A Tale of Missed Checks and Shouted Specs

Ah, the life of a contractor—where every day is an adventure, and you’re the hero armed with nothing but your wits and a laptop. Like Indiana Jones, I’ve managed client expectations and communication challenges. Here’s the lowdown on surviving the wilds of workplace woes with a grin.

Chapter One: The Case of the Missing Validity Checks

Once upon a time, I suggested to a Project Manager (PM) that we should probably check the content of a PowerPoint display before chucking it into the gaping maw of Confluence. He, in his infinite wisdom, proclaimed such checks unnecessary. “Just migrate it!” he declared. So, migrate I did. Mere days later, he scrapped the content himself because—plot twist!—it was outdated. Who could’ve guessed? Well, me… I did guess. However, in later collaborations, he had a sense of humour failure and raised his voice in frustration more than once.

Chapter Two: The GDPR Fiasco

Imagine, if you will, a GDPR project where the document looked like a horde of angry red pen-wielding vandals had attacked it. I dared to point out that the riot of track changes made the document as readable as ancient hieroglyphs without a Rosetta Stone. The PM’s reaction? A not-so-mighty roar in front of a dozen coworkers. Yikes! One week later, unable to cope, he walked away.

The Golden Rule: Set Expectations Like Setting Traps in the Jungle

To keep the wild beasts at bay (read: client frustrations), start every project by setting crystal clear expectations. Draw them a map with X marks on the spot, showing timelines and task breakdowns. Clients who know what to expect are less likely to go on a rampage when deadlines sneak up on them.

Educating the Natives (I Mean, Clients)

Empowering your clients goes a long way. Show them the path you’ve charted, step-by-step, so they feel part of the journey rather than just baggage being lugged around. It turns suspicious glares into nods of approval and keeps the peace in the village.

Broadcasting Updates: Not Just for Sports Channels

Keeping clients in the loop with regular updates is crucial. It’s like sending smoke signals to assure them that the project is still on fire (in a good way). This constant connection is the secret sauce to a successful client relationship; communication, not telepathy, keeps things smooth.

The Art of Feedback and the Grace of Boundaries

Allow space for feedback—it’s like a safety valve that lets off steam and realigns tracks as needed. Also, be like a serene monk when confrontations arise: acknowledge the thunder, but don’t let it shake you. Stick to your quality guns, and don’t let yourself be rushed.

Dealing with Workplace Wildlife

When faced with a fuming boss or a power-tripping manager, remember, it’s not just about surviving but knowing when to pack up your tent. Whether it’s taking your grievances to HR or simply walking away, choose your battles wisely.

In Conclusion: Be the Contractor Who Wrote the Book

Contracting isn’t just about delivering spiffy spreadsheets and snazzy slides; it’s about crafting an experience so transparent and smooth that even the most demanding clients want to bookmark you for a sequel. So there you have it, a guide to thriving in the contracting jungle—may your communications be clear and your expectations managed like a pro!