Category: Technical Writing

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.

Technical Authors: Do you need a new job title

Do technical authors need a new title due to changing roles?
Ask a question: When you hear the job title Technical Author, what is the response?
My most recent response emphasised upholding the integrity of the technical documentation.
The crux is that the role of a technical author has shifted in the last 10–15 years. Many find that their day-to-day work no longer matches their job title. Let’s break it down:

The Traditional Job Title

      • A Technical Author meant someone who wrote manuals, user guides, or specifications.
      • The focus was on producing text-heavy deliverables that explained systems, processes, or products.
      • The work was bound and recognisable — you delivered documents.

The Modern Reality

Today, we do far more than write:

      • Information architecture: structuring knowledge bases, designing content workflows, or building taxonomies.
      • Content strategy: deciding what to document, why, and in what format (DMS, CMS, wiki, KB, PDFs, APIs, microcontent).
      • Process design: defining review loops, approval gates, and compliance documentation.
      • Tools & technology: working with Asite, SharePoint, Git, MadCap Flare, Confluence, or API documentation platforms.
      • Training & enablement: running workshops, teaching engineers to write, or creating templates and style guides.
      • Governance & compliance: PCI/DSS, ISO 27001, GDPR, and other regulated frameworks often fall into our remit.
      • In short, the “writing” is still there, but it’s often 20–40% of the role. The rest is closer to content management, knowledge management, or even business analysis.

The Tension

If your business card says Technical Author, but you spend most of your time on:

      • structuring SharePoint sites,
      • managing metadata,
      • training colleagues,
      • support
      • Or developing a documentation strategy,

…then the title undersells both your contribution and your market value. It can also confuse managers, who may assume you’re “just a writer” and overlook your broader impact.

Evolving Job Titles

Some organisations have already rebranded the role. Common alternatives:

      • Technical Writer (US equivalent, though still too narrow).
      • Content Designer (favoured in government/service design circles).
      • Documentation Manager or Information Manager.
      • Knowledge Manager (especially when linked to systems like Confluence or Asite).
      • Content Strategist (if you lead on planning/documentation governance).
      • Information Architect (if your role is very structural and metadata-driven).
      • Document Management (SharePoint) administration

Why a Title Change Matters?

      • Recognition: Reflects the breadth of what you do.
      • Career Progression: Opens paths into strategy, KM, or management.
      • Market Value: Recruiters and hiring managers may undervalue a “technical author” compared to a “knowledge manager” or “content strategist.”
      • Personal Motivation: Titles can shape how you (and others) view your role.

A Balanced View

That said, there’s value in keeping “technical author” alive — it is still a recognised profession, and many industries (engineering, aerospace, IT) rely on that clarity. The trick is whether your work is still 80% authorship or whether the writing part has become a byproduct of a much larger scope.

Conclusion:


If you now spend more time on governance, strategy, architecture, and training than writing, then yes, the title Technical Author may no longer serve you. It hasn’t reached “end of life” as a profession (there’s still plenty of need for core documentation specialists), but your role might have evolved into something broader. The challenge is to choose a new title that captures both your expertise and the value you bring.

Technical Author: Role Evolution

Focus Area
 Typical Tasks Best-Fit Job  Title(s) When to Consider Moving On from ‘Technical Author’
Writing & Editing Creating manuals, procedures, work instructions, help files, API docs Technical Author / Technical Writer When 70–80%+ of your work is direct writing & editing
Content Design Chunking info for different audiences, plain English editing, and UX copy in docs Content Designer When you focus on clarity, accessibility, and user experience more than raw documentation
Information Architecture Designing knowledge bases, metadata, tagging, navigation, and cross-references Information Architect / Documentation Specialist When your most significant value is structuring & organising content
Documentation Management Setting up DMS/CMS (Asite, SharePoint, Confluence), version control, workflows Documentation Manager / Information Manager When you spend more time managing systems and processes than writing
Knowledge Management Building FAQs, wikis, self-service portals, and the reuse of knowledge assets Knowledge Manager When your role is less about producing new docs and more about curating knowledge
Governance & Compliance Writing/maintaining ISO 27001, GDPR, PCI/DSS docs; ensuring audit readiness. Compliance Documentation Specialist / Information Governance Lead When compliance and audit trails dominate your workload
Content Strategy Deciding what to document, defining style guides, setting standards, and aligning with business goals. Content Strategist / Documentation Lead When you’re steering what gets written rather than writing it yourself
Training & Enablement Running workshops, creating templates, and teaching engineers to write in plain English. Documentation Trainer / Writing Coach / Knowledge Enablement Lead When you’re teaching and enabling others more than authoring content
Cross-Discipline Hybrid Doing a mix of writing, managing, training, strategy, and systems work Senior Technical Author / Information Manager / Content Strategist When no single title fits, seniority helps cover the broader remit

Takeaway

  • If most of your time is still spent on writing, “Technical Author” is valid.
  • If you’re spending 40–60% of your budget on architecture, governance, or strategy, a change of title boosts clarity and credibility.
  • If you’re leading systems, compliance, or KM, your role is no longer just authoring — you’re managing knowledge and strategy.

Software Upgrade Amid User Guide Update Challenges

Berkshire-based XYZ Releases Software Upgrade Amid User Guide Update Challenges

In the competitive software market, staying current is crucial, and Berkshire’s own XYZ company has just taken a significant step forward with the release of its upgraded software product, Version 3.0. This upgrade introduces considerable improvements in functionality.

However, they do not mention the associated user guide, which has remained untouched for over seven years.

Critical Need for an Updated User Guide

As XYZ prepares to roll out these enhancements, the spotlight turns to the 200-page user guide—untouched since its creation. They have contracted a local technical author to update and include the software’s expanded capabilities.

Challenges in User Guide Revision

The technical author (TA) faced hurdles from the start. The user guide, written by multiple authors in Germany, is inconsistent and outdated. Poor coordination between writers in the original guide has complicated this update.

Timeline Realities and Project Management Issues

The update is urgent, but the TA estimates 9 to 18 weeks, longer than the three-week deadline before the software’s release. The project sponsor soon learns that writing documentation is a challenging job.

The Conversation

When the TA starts, no one knows the location of the UG, and it takes several hours to track a copy. When he begins his analysis, he notes multiple errors, spelling mistakes and inconsistencies.

Meanwhile, the Project Sponsor (PS) observes the TA and notes his lack of activity. She emails the internal recruiter, who speaks to the TA on his second day about the lack of activity and wants to see progress. The TA confronts the PS at her desk to hear her explain her concerns.

Project Sponsor (PS): Yesterday, you started and sat at that desk and barely moved. We have three weeks to update the user guide, and I expect more progress by now.

TA: Three weeks! The UG contains over 200 pages written by multiple authors. I must review each section to ensure I understand the software.  The document is a mess with multiple mistakes and inconsistencies.

PS: I thought people like you reviewed the document and made the changes quickly.

TA: That user guide requires significant work. I must understand the content, which is not clear in many places. Do you know the reality of updating such a large document?

PS: I have a feeling you are going to tell me.

TA: On top of my head, an estimation of this update could take up to 15 weeks.

PS: 15 weeks. How?

TA: 1-2 weeks to understand the scope, plan the document’s structure, and prioritise sections. I need access to software to take new screenshots and talk to the SMEs. 3-6 weeks to write updates and incorporate new functionalities. Then, reviews, feedback, and revision cycles. Revising over 200 pages is no walk in the park. Then, two weeks for final edits, formatting, and publishing of the updated guide. It will take 9 to 18 weeks to update your user guide.

PS: Can you not do it faster?

TA: No, it’s impossible.

PS: we need another TA. we can’t use you!

TA: Getting a new TA won’t fix your problem. A TA with integrity will tell you the same. Even two TAs could not complete this in three weeks.

PS: This is frustrating. I don’t want to hear about delays. I want a solution.

TA: you should have started this project three months earlier if you wanted it ready for release in three weeks.

PS: (scoffs) The budget wasn’t available then! We wanted a TA a month ago, and you were the only one available.

TA: TAs are in short supply.

PS: (sighing with disbelief at what the TA has told her).

TA: Did you think the problem would solve itself?

PS: That’s not fair! We’ve had a lot of competing priorities.

TA: Not my problem, but it’s a reality. This project had failed before it started. You’ve set yourself up for failure if you don’t prioritise quality documentation. It also reflects on the product and your company’s professionalism. I have a professional reputation, which I will not compromise. I will leave this project to avoid unnecessary pressure because of unrealistic expectations.

PS: So, what are you saying? We can’t accept that we won’t meet the deadline.

TA: Yes, you need to extend the timeline if you want a professional job.

PS: The allocated budget only covers you for three weeks. I can’t accept this. I’ll have to think about it.

TA: Fair enough. But it will take three weeks to outline the document and won’t cover the writing process—the clock ticks. I have done this job long enough to know the timelines, and I’m not exaggerating. You have left this too late.

Essential Points for Efficient Project Outcomes

    1. Early Initiatives: Starting updates early is essential to manage expectations and deliver quality.
    2. Time Demands: Thorough updates for large documents require substantial time.
    3. Realistic Planning: Setting achievable deadlines is critical to avoid rushed jobs and potential frustration.
    4. Quality Focus: High-quality documentation ensures user satisfaction and reduces support costs.
    5. Resource Management: Proactively securing skilled technical authors ensures that documentation keeps pace with software development.
    6. Effective Communication: Clear discussions between project stakeholders prevent misunderstandings and align project goals.
    7. Budget and Resource Planning: Anticipating financial and staffing needs prevents last-minute crises and ensures comprehensive project coverage.

Looking Ahead

As XYZ company navigates these challenges, the lessons learned underscore the importance of strategic planning and realistic project management in software development. Ensuring the user guide matches the software’s quality not only enhances user experience but also reinforces XYZ’s commitment to excellence.

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!

How to Win Over Management and SMEs: A Hilarious Guide for Technical Authors

So, you’ve embarked on the noble quest of a technical author. Your mission, should you accept it (and you have no choice), is to convert the mighty management and the enigmatic SMEs (Subject Matter Experts) to your way of thinking. Sounds like a Herculean task? Fear not! Here’s your humorous guide to charming them into submission while keeping your sanity intact. Remember, we’re all in this together, united by the common goal of effective communication. So how to Win Over Management and SMEs to your way of thinking.

Speak Their Language (No, Not Klingon)

Let’s be honest—management speaks in KPIs and ROI, while SMEs converse in an ancient dialect known only to a few. Your first step is to become a polyglot. Learn to weave your documentation magic into business objectives and arcane technical details. It’s like being a translator at the United Nations but with less chance of starting an international incident.

The Art of Presentation: Smoke and Mirrors

With communication, clarity icriticaley. But why stop there? Make your points with the flair of a Las Vegas magician. Use charts, graphs, and infographics that sparkle. And remember, nothing says “I know what I’m talking about” like a well-timed meme. Trust me; pie charts are irresistible to management as cat videos are to the internet. Please don’t overdo it, or you will end up in a meme yourself!

Quick Wins: The Fast and the Furious

Management loves results faster than a pizza delivery. And who’s the hero delivering those results? You, the technical author. Identify accessible opportunities and deliver those quick wins like Vin Diesel in a muscle car. A tiny tweak will save an hour of work each week or a new tool that doesn’t require a PhD. Shout about those victories with the enthusiasm of a game show host handing out prizes. You’re the star of this show.

Collaboration: Herding Cats, but With Treats

Getting management and SMEs to work together is like herding cats, but don’t worry—we have treats! Engage them early with workshops that are part of brainstorming and therapy sessions. Provide plenty of coffee and snacks; they’re more likely to engage if their blood sugar levels are stable. Plus, who argues over a cookie?

Build Relationships: Be the Office Barista

Relationships are everything. Become the office barista—always ready with a listening ear and coffee. Trust and rapport are your best friends. Remember, it’s harder to say no to someone who knows your coffee order by heart.

Highlight Long-term Benefits: The Crystal Ball Approach

Paint a picture of a future so bright they’ll need shades. Highlight how your approach will lead to fewer headaches, lower costs, and maybe even a tropical vacation (we can dream). Show them the long-term benefits with the enthusiasm of a late-night infomercial host. “But wait, there’s more! If you adopt this strategy now, you’ll also get…”

Embrace Technology: The Cool Kid in School

Introduce new tools and technologies like you’re showing off the latest gadget. Be the cool kid who knows all the shortcuts and secret features. Offer training sessions, but make them fun—think less “seminar” and more “techno party.” Bonus points if you can throw in a few tech-related jokes. “Why do programmers prefer dark mode? Because light attracts bugs!”

Example Scenarios:

      • Scenario 1: Management Concerned About Cost: “Dear Management, investing in this new tool is like buying a golden goose. It’s pricey upfront, but think of the endless eggs. In financial terms, that means reduced time, fewer errors, and overall productivity that will make our competitors weep.”
      • Scenario 2: SME Resistance to Change: “Dear SMEs, we know you love your ancient rituals, but imagine a world where documentation is a breeze. Join our workshop—there will be snacks!—and let’s create a workflow so smooth, you’ll forget what life was like before.”

Ultimately, winning over management and SMEs is about strategy, charm, and humour. So, arm yourself with these tips and spread the word about the importance of good documentation. Keep in mind that these strategies have been tried and tested. If all else fails, remember that bribery with baked goods is always an option. With these tools, success is inevitable.

Tales from the Desk of a Technical Author

In the world of technology, unsung heroes lurk in the shadows, wielding their pens (or keyboards) to document the wonders of code, hardware, and software—in my case, training materials, editorial, and consulting. Yes, we’re talking about technical authors—the wizards of words, the maestros of manuals, and the unsung champions of clarity in a sea of tech jargon. The profession of technical authorship has a rich history, dating back to the early days of computing when the need for clear, concise documentation became apparent.

Contrary to popular belief, technical authors have a fun job that goes beyond following rules. So, buckle up and prepare to embark on a journey into the quirky world of technical authorship! To excel in this field, one needs a strong command of language, the ability to understand complex technical concepts, and a knack for simplifying them for a non-technical audience.

First, let’s debunk the myth that technical authors are mere writers. Oh no, my dear reader, we are much more than that. We are the bridge builders of the tech world, straddling the chasm between siloed departments with the finesse of a tightrope walker on caffeine.

Do you need help?

    • To translate developer jargon into plain English? 
    • Are you deciphering the cryptic scribbles of the engineering team? 

Rest assured, we’ve got you covered. Whether it’s translating developer jargon into plain English or deciphering the engineering team’s cryptic scribbles, we are here to unravel the mysteries of their chicken scratch.

But wait, there’s more! We are:

    • The masters of documentation management.
    • The Jedi knights of version control.
    • The guardians of the sacred art of template creation.

Need a document wrangled into submission?

Call us. Need help with the intricacies of your company’s document management system?

Call us, and we’ll swoop in like caped crusaders armed with spreadsheets and flowcharts.

And let’s remember our diplomatic prowess. Amid a heated debate between rival factions over placing a comma in a user manual, who swoops in to save the day? Your friendly neighbourhood technical author, armed with a cup of tea and a voice to calm even the most agitated developer.

That’s right, your friendly neighbourhood technical author, armed with a cup of tea and a voice to calm even the most agitated developer.

But our greatest superpower lies in our ability to transform mortals into document-writing virtuosos. Fear not. When a colleague struggles to string together a coherent sentence, we shall sprinkle our magic writing dust upon them and watch them blossom into wordsmiths.

When you next encounter a technical author, dear reader, consider the depth of their skills and influence as the unsung hero of the tech world. We deliver well-written manuals, crafted templates, and harmonious team collaboration. Our work is not just about writing; it’s about working closely with developers, engineers, and other team members to ensure that the final product is of the highest quality.

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.

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.