Unlocking the mystery of accessible documentation: My Guide

Welcome to the world of technical documentation, where the language feels like embarking on a quest for the Holy Grail. But fear not, fellow adventurers! With a dash of humour and a sprinkle of wit, let’s delve into the whimsical realm of enhancing accessibility in these oh-so-serious documents.

First things first, let’s talk language. Ah, yes, the tangled web of jargon and acronyms. It’s like trying to decipher ancient hieroglyphs without a Rosetta Stone. So, here’s a radical idea: let’s ditch the mumbo-jumbo and speak in plain old English! Novel concept, right?

How about formats? Forget your run-of-the-mill text documents; we’re discussing HTML, PDFs, and audio and video formats! Who doesn’t love an excellent interpretive dance to explain the intricacies of coding? Break out the jazz hands, folks!

What about visuals? Charts, diagrams, and images are all good until you realise they’re about as descriptive as a mime trapped in an invisible box. Cue the alternative text! Describe those images like you’re narrating the most epic tale ever. Bonus points for creativity!

The saga of fonts and typography? Forget about Comic Sans and Times New Roman; we’re in the era of font liberation! Choose your fonts, for they shall guide you through the difficult journey of readability and contrast.

The structure is our trusty steed on this epic adventure. Headings, subheadings, and bullet points are the knights in shining armour, battling the dreaded Wall of Text to save us from writer’s block.

Finally, user feedback. So speak up, fellow travellers! Your feedback could be the key to unlocking the mysteries of accessibility once and for all.

So folks, with humour and creativity, we can transform the world of technical documentation into an adventure. So grab your sword (or keyboard) and join us on this epic quest to make documentation accessible for all!

Technical authors : a technical document nightmare

The chaos of Technical Documentation Management: A guide to saving your sanity

The document management system presents a formidable challenge to oversee. Documents flow in and out, undergo changes and deletions, and find their place in the archives. In the middle of this, the document controller resembles a conductor orchestrating the music to the epic tune of Wagner’s “Ride of The Valkyries.”

So, if you are one of the many who control technical documentation, what is your state of mind?

The Agony of the Document Controller: A Tragicomedy

The document controller struggles to keep up with the never-ending flow of documents. Despite having guidelines to follow, it feels like an endless task. For every correctly filed document, ten more appear that are mislabelled and misplaced. People who refuse to comply fill the inbox with excuses.

Expectations vs. Reality: The Grand Illusion

Documents must be well-tagged, searchable, and updated without straining muscle. However, they have confusing titles, and the search function can be unreliable, leading to error messages instead of desired results.

Where is that document?

Complaints flood in from frustrated users because the expected title is not in the search results, which run into the hundreds. Why, you ask? Because the document does not have the correct title because of the creativity of the document authors. 

Heed my words: It’s common to believe everyone will follow document naming conventions. Still, creativity thrives in the chaos of file naming, leading to an imprecise array of document titles. This is one error on the path to documentation anarchy. 

Training… Must I do that?

Refrain from assuming that training sessions on the document management system will be as popular as a free lunch seminar. In reality, it’s more like hosting a party where the only person attending is the echo of your voice reminding people to use metadata tags.

A Beacon of Hope: Persuasion Over Coercion

But do not fear, as there is still hope. Our document controller, armed with humour and unwavering patience, embarks on a quest to turn the tide. They learn that persuasion, sprinkled with humour, is mightier than the sword (or the forceful email).

Creating engaging tutorials that don’t induce sleep, gamifying the process of correct document submission, and celebrating small victories with the team can turn the tide. Suddenly, the document management system isn’t a beast to be feared but a puzzle to be solved.

Technical Author | In my opinion

In my opinion

As a technical author, I often hear the phrase “in my opinion”. What that means is a colleague doesn’t trust your judgement and thinks they know better. Some skilled engineers and project managers told me they understand technical authoring better than I do. They consider their documents through rose-coloured spectacles as ‘Good’, leading to a difference in the definition of’ good’. They avoid asking me to review it, but when the boss notices discrepancies, he asks for a second opinion. Cue me and my trained eye. 

After I completed the editing, the document author found his written work and formatting did not make the mark. At best, 4/10 for effort. If you think I am harsh and turn a blind eye and let the occasional error go through, where does that lead us?

I recall an interview I had in Great Missenden. The hiring manager showed me some documents. When I commented about the poor writing, he revealed he wrote them himself. The look on his face said it all. He thought it was a good document. The interview ended for me. But how far does he believe his documentation will go if he cannot listen to criticism? Granted, I forgot about diplomacy when I asked, but I didn’t expect him to be the writer. I expect someone down the company hierarchy to have written documentation when the hiring manager is keen to show me what they have.

The question: how must technical authors handle differences of opinion? And what can managers do to ensure that the technical documentation meets the required standards?

When I critiqued a document, I balanced my professional expertise and interpersonal relationships. Managing this situation requires a combination of diplomacy, clear communication, and a constructive approach. You learn lessons along the way, and years later, I had an approach to handling such situations.

For Technical Authors:

      1. Focus on Collaboration, Not Criticism: Present your feedback as a joint effort to enhance the document’s intended purpose. Position yourself as an ally rather than a critic.
      2. Use Evidence-Based Feedback: Base your feedback on specific technical writing standards, guidelines, or best practices. Make your critique aim rather than personal.
      3. Highlight Strengths First: Start with positive feedback before pointing out areas for improvement. Acknowledging what works well can make the recipient more receptive to constructive criticism.
      4. Offer Solutions, Not Just Problems: Suggest improvements to prevent defensiveness.
      5. Educate on Best Practices: Sometimes, the discrepancy in expectations arises from a need for more awareness. Briefly explaining why we must follow certain practices in technical writing can bridge this gap.
      6. Seek Understanding: Try to understand the author’s original intent with the document. Provide feedback that aligns with their goals while improving the document’s quality.
      7. Choose the Right Medium for Feedback: Avoid misinterpretation by discussing input through in-person calls for immediate clarification and discussion.

For Managers:

      1. Set Clear Standards: Establish and communicate clear standards for technical documentation. Providing templates, style guides, and examples of good documentation can set a clear benchmark.
      2. Facilitate Training: Offer training sessions on technical writing to non-writers. Understanding the basics of good technical writing can improve the initial quality of documents.
      3. Encourage a Culture of Feedback: Promote a culture where feedback is an opportunity for growth, not criticism.
      4. Implement a Review Process: Create a review process to vet documents for quality before finalisation.
      5. Support Technical Authors: Support technical authors, and back them up when challenged by colleagues.
      6. When technical expertise clashes with personal pride, encourage dialogue to mediate conflicts and find a balance.
      7. Recognise and Reward Quality Work: Acknowledge high-quality documentation to prioritise quality in their work.

Technical authors can manage opinions and improve documentation quality by adopting these strategies. Managers can also ensure that the documentation meets the required standards. When people work together, it improves the quality of technical documents and helps projects succeed.

Technical Authors | what does good look like

What does good look like? 

How do we establish a shared understanding and define what ‘Good’ looks like for presenting information in an organisation? Everyone has a different opinion. If we cannot apply what good looks like, it results in problems in writing and preparing technical documents. 

The question touches on a common scenario in the tech industry. We have individuals or teams writing technical documentation. They shun our expertise because they want to look good. This approach leads to mixed outcomes when the document writer needs more skills. So, what does good look like?

Here’s a deeper look into the dynamics of this situation:

Self-Assessment vs. Professional Standards

    • Confidence vs. Competence: non-technical authors write technical documentation based on their understanding of the subject matter. However, good technical documentation requires more than just subject matter expertise; it requires the ability to present information accessibly.
    • Underestimating the Skill Set: Technical writing requires clear communication and deep technical knowledge. It also involves understanding the user’s perspective. That can be challenging for those deeply ingrained in the technical details of a product.

Feedback and Improvement

    • Receiving Critique: When non-specialists craft technical documents, professional technical authors’ feedback can highlight the lack of clarity, conciseness, organisation, and user focus. This critique improves the documentation’s effectiveness and is not a personal insult.
    • The Value of Expertise: Professional technical authors bring specialised skills, including
      • audience analysis,
      • information architecture,
      • writing clarity, and
      • the ability to distil complex information into understandable content.

Their expertise is in writing and understanding how people search for, comprehend, and use technical information.

Recognising Good Technical Documentation

      • Clarity and Conciseness: Good documentation conveys complex information easily, avoiding unnecessary jargon and focusing on what the user needs to know.
      • Organisation and Accessibility: It is well-structured, making it easy for users to find the information they need. Good documentation anticipates user questions and provides answers in a logical flow.
      • Accuracy and Reliability: It must be technically accurate and up-to-date, giving users confidence in its instructions and information.

The Role of a Good Technical Author

An excellent technical author bridges the gap between complex technicalities and user comprehension. They:

      • Understand the technology and the audience.
      • Skilled in creating helpful content.
      • Employ best practices in technical communication to ensure documentation is adequate.

Conclusion

Our standards, specialised skills and perspectives separate us from the self-assessed Competence. Recognising the value of this expertise enhances the quality of technical documentation. Understanding what good technical documentation looks like—and the role of a technical author in achieving it—is crucial for anyone involved in creating or overseeing the creation of technical documents.

That’s what ‘Good’ looks like!

 

Technical Authors | How important are we?

A manager hired a technical author to write project documentation. However, the final document failed to meet expectations. The writer did not consult with the subject matter experts (SMEs) and as a result, the document failed to provide answers to questions.

A hiring manager asked about the significance of technical authors in a project. He had hired someone to write the project’s documentation. Unfortunately, the final document did not meet expectations. The hiring manager had hoped that the documentation would provide answers to questions. However, the writer produced a document without consulting subject matter experts (SMEs). As a result, the document failed to meet expectations. 

The issue: Leaders don’t understand what we do. Here are some critical aspects of his dilemma: 

Recognising the Mistake: The manager acknowledged not hiring a technical writer meant a loss of information. 

Comprehensive documentation is essential to prevent the manager from being bombarded with daily questions. 

Impact on Productivity: Well-documented processes and procedures enhance the team’s productivity. 

Post-Project Challenges: The absence of proper documentation poses challenges post-project. It makes maintenance, knowledge transfer, and support more difficult and costly. 

Underestimating Technical Author Expertise: No one recognised our expertise.

Future Planning: To acknowledge the significance of technical documentation in all upcoming projects. If you hire us in the project planning phase, we can ensure a complete documentation process throughout the project lifecycle. 

Learning from the Experience: The manager knows our expertise exists and we can enhance the success of a project. 

In the short term, the manager needs to deal with the challenges caused by the lack of documentation. This might involve documenting critical information or finding alternative solutions to the daily questions. The manager’s dilemma underscores the importance of technical documentation. It emphasises the value of technical authors at every stage of the project’s development.

IT Audits: a Technical Authoring view

IT Audits: A technical author’s view from the front line. I have worked on several projects, including an audit of a company’s IT ahead of a migration from one data centre to another. In three cases, no documentation existed; in the fourth, documentation was scattered around in various places.

IT Audits

IT Audits: A technical author’s view from the front line. I have worked on several projects, including an audit of a company’s IT ahead of a migration from one data centre to another. In three cases, no documentation existed; in the fourth, documentation was scattered around in various places.

Data Centre migrations

An IT audit focusing on a data centre migration project aims to ensure the process is well-planned and executed to minimise risks, guarantee operations and data integrity continuity, and adhere to relevant standards and regulations. This article introduces the data centre migration audit concept and what it entails.

Documentation Required

The project will require several documentation types. As the project rolls on,  the project managers will develop their documents, such as progress spreadsheets. As a Technical Author, our focus is on the following documentation:

Profile documents – these are recommended if there is little to no documentation in existence. These documents contain high-level information. You will need one per server and list all the information such as users, dependencies, DR requirements, what it hosts, data flows In/Out and much more. I can supply a full list on request.

Operating Documents: These contain Profile information plus more granular information. The receiving team uses them as comprehensive information backup and must be stored in an accessible location.

Installation Documents – these provide valuable installation processes using the company’s configurations. These must also be stored in an accessible location.

Knowledge Transfer – to ensure everyone reads from the same page, collects knowledge from SMEs and shares it in an accessible location.

Purpose of the IT Audit in Data Centre Migration

  • Risk Assessment: To identify and assess risks associated with the migration, including:
      • data loss,
      • downtime,
      • security vulnerabilities, and
      • compliance issues.
  • Process Evaluation: To ensure that the migration process follows
      • organisational policies,
      • including project management,
      • change management, and
      • quality assurance.
  • Verification of Data Integrity and Security: To verify:
      • data integrity
      • implement security measures for data protection
  • Compliance Check: To verify adherence to relevant regulations and standards (e.g., GDPR, HIPAA, ISO/IEC 27001) that may impact the migration process.
  • Post-Migration Review: To evaluate the success of the migration in terms of meeting its objectives, including:
    • performance benchmarks,
    • cost-effectiveness, and
    • achieving planned benefits.

Critical Components of the Audit Process

  1. Pre-Migration Planning: Evaluating the thoroughness of the migration strategy, including:
    • assessing the current data centre’s architecture,
    • the migration’s Scope, and
    • the target environment’s readiness.
  1. Implementation Review: Analysing the execution of the migration to ensure it aligns with the following:
    • planned procedures,
    • project timelines, and
    • This includes reviewing the technical approaches, such as
    • data replication,
    • network reconfiguration, and
    • application migration strategies.
  1. Security Measures: Assessing the security protocols implemented before, during, and after the migration to safeguard data and infrastructure. This encompasses access controls, encryption, and security monitoring tools.
  2. Data Integrity Verification: Ensuring that data transferred during the migration is accurate, complete, and unchanged. Techniques such as checksum verification and data reconciliation are part of this process.
  3. Business Continuity and Disaster Recovery (BC/DR) Planning: Reviewing the effectiveness of BC/DR plans in the context of the migration, including the ability to recover data and maintain operations in the event of a failure.
  4. Post-Migration Validation: Conducting a thorough review after the migration to ensure that all systems operate as expected in the new environment. This includes performance testing, functionality verification, and ensuring that you achieve the migration objectives.
  5. Documentation and Reporting: Reviewing the completeness and accuracy of documentation related to the migration process, including planning documents, execution records, and post-migration evaluations. The audit will conclude with a detailed report highlighting findings, recommendations, and any identified issues.

Managing the Audit Process

    • Stakeholder Engagement: Involving critical stakeholders throughout the audit to ensure alignment and address concerns.
    • Use of Tools and Technologies: Leveraging specialised tools for data migration, security assessment, and project management to facilitate a thorough audit.
    • Expertise: Engaging with IT auditors with experience in data centre migrations and understanding the technical, operational, and compliance aspects of such projects.

Preparing for an IT audit involves a comprehensive review and documentation of your organisation’s IT infrastructure, policies, and procedures. The goal is to ensure your IT environment aligns with best practices, legal and regulatory requirements, and industry standards. Here’s a step-by-step guide on how to prepare for an IT audit focusing on documenting the network, servers, data flows, and disaster recovery (DR) outlines:

Understand the Audit Scope and Objectives

    • Identify the Type of Audit: an internal or external audit and the standards or guiding regulations (e.g., ISO/IEC 27001, GDPR, HIPAA).
    • Define the Scope, including specific systems, processes, or locations.

Assemble a Core Team

    • Select a diverse team of subject matter experts (SMEs) from different areas of your IT environment (network, server administration, data management, security, disaster recovery).
    • Designate a project manager with strong organisational and communication skills to lead the documentation effort.
    • Overseas Infrastructure: If the company has European offices, make contingencies for language barriers.

Designate a Point of Contact (POC)

    • Choose a POC fluent in English and possibly other languages spoken by team members to manage all communications effectively.
    • This person should have a good technical understanding and excellent communication skills to bridge language or technical gaps.

Consider Direct Meetings

    • If feasible, arrange for technical authors, or project leads to meet with overseas colleagues in person.
    • Direct interactions can foster better understanding, clear up ambiguities, and build stronger team cohesion.

Kickoff Meeting

    • Hold a kickoff meeting to outline the documentation project’s goals, process, and importance.
    • Use clear, simple language and visual aids to ensure understanding across language barriers.
    • Discuss the need to create a high-level profile document.

Document Collaboration

    • Utilise collaborative tools like shared documents, diagrams, and project management software that support comments and revisions.
    • Ensure the tools chosen are accessible and user-friendly for team members with varying technical expertise and language proficiency levels.

Collect Basic Information

Start by collecting high-level information about the IT infrastructure to create the profile document:

    • Network architecture: Outline the basic network design, including principal components like routers, switches, firewalls, and connectivity layout.
    • Servers and devices: List critical servers, their roles (e.g., web server, database server), and other critical devices.
    • Data flows: Identify central data flows within the network, highlighting the sources, destinations, and data processing stages.
    • Disaster recovery (DR) outlines: Provide a brief overview of the existing DR strategies.

Document the Network

    • Create or Update Network Diagrams: Include all network segments, connections, and critical devices (routers, switches, firewalls).
    • Identify Critical Assets: Mark systems that store, process, or transmit sensitive information.
    • Network Segmentation: Document how the network is segmented, especially areas with sensitive data.
    • Document Servers and Systems
    • Inventory: List all physical and virtual servers with their roles, operating systems, and critical applications.
    • Configuration Standards: Document the configuration standards for each type of server.
    • Access Controls: List access control measures in place for each server.

Document Data Flows

    • Data Flow Diagrams: Create diagrams showing how data moves through your systems, highlighting where data is stored, processed, and transmitted.
    • Data Classification: Document data classification (e.g., public, confidential, sensitive) and the controls in place to protect it based on its classification.
    • Third-Party Data Sharing: Document any data shared with or received from third parties, including the controls and agreements in place.

Use Visual Aids

    • Create simple diagrams and charts to visualise the network layout, data flows, and server organisation.
    • Visual aids can be crucial for overcoming language barriers and ensuring accurate understanding across teams.

Schedule Regular Updates and Reviews

    • Set up regular meetings or video calls with the core team and other SMEs to review the progress, clarify doubts, and validate information.
    • Use these sessions to address any misunderstandings or language-related issues promptly.

Create a Glossary

    • Develop a glossary of terms and acronyms used in the documentation to ensure everyone understands the terminology clearly.
    • This team members for whom English is a second language.

Document Disaster Recovery

    • Document Disaster Recovery (DR) Plans
    • DR Strategies: Outline strategies for data backup, recovery sites, recovery point objectives (RPOs) and recovery time objectives (RTOs).
    • DR Procedures: Document detailed DR procedures for different scenarios (e.g., data breach, natural disaster).
    • Testing Records: Include records of DR plan testing, issues identified, and corrective actions taken.

Review Policies and Procedures

    • Ensure all IT policies and procedures are up-to-date and compliant with relevant standards and regulations, including access control policies, data protection policies, and incident response plans.

Review and Feedback Cycle

    • Implement a thorough review and feedback cycle involving all SMEs to ensure the accuracy and completeness of the documentation.
    • Be open to feedback and willing to make adjustments based on insights from team members with different perspectives.

Conduct Internal Assessments

    • Perform a self-assessment to identify gaps in documentation, policies, or procedures.
    • Use checklists or auditing tools to simulate the audit process.

Training and Knowledge Transfer

    • Conduct training sessions to review the documents and ensure everyone understands the content.
    • Use these sessions to refine the documentation further based on questions and feedback.

Conclusion

An IT audit for a data centre migration is critical in ensuring that the migration is executed effectively and securely and complies with all relevant requirements. By systematically evaluating each migration phase, organisations can proactively mitigate risks, address potential issues, and ensure a smooth transition to the new environment.

 

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.

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!

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? 

We’ve got you covered, and fear not; we shall 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. Oh yes, dear reader, technical authors are the peacemakers of the tech world, armed with the patience of saints and the diplomacy of ambassadors. Picture this: a heated debate between rival factions over placing a comma in a user manual. Who swoops in to save the day?

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 is our ability to transform mortals into document-writing virtuosos. Is the colleague struggling to string together a coherent sentence? Fear not, for we shall sprinkle our magic writing dust upon them and watch them blossom into wordsmiths before our eyes.

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.

 

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.

Technical authors, give your career a shot in the arm. Learn how to plan documentation projects. 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. It takes longer than project managers realise. 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.

Project plans may face issues when updates require time-consuming document review and revision phases.

Project managers and technical authors 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

In 2004, while staring at redundancy for the third time, I accepted a six-month contract with BT to fill a potential gap until a permanent role emerged. A former colleague told me that contracting can be a long-term career choice. However, transitioning from a contract to a permanent position can be challenging. 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 their HQ in Ipswich. Then came T-Mobile (now EE), NTTE, and Capita. Before I knew it, five years had gone by, and recruitment agents were calling with contract and permanent jobs. 

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.

So, every year, I hopped from one contact to another on multiple tasks, occasionally meeting TAs with stories on workplace experiences; we all understood each other and provided a laugh. 

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, allowing me to pay myself an inconsistent amount every month. During the 2008 financial crisis, my earnings dropped by a massive 33%, not helped 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 when 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 widen my experience, but I also travelled to Pune in India, 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. When we arrived, the PM had used most of the budget to prepare for an audit, which involved hiring an expensive external consultant with high fees.

We needed to prepare the groundwork, identify SMEs, and divide the sixty titles between us. After five weeks, we began talking to SMEs and writing the documents. But the task was beyond our efforts—too much to do and insufficient time. While the company in question went bust during the pandemic, it had nothing to do with the project. 

Hiring managers and project managers often struggle with the dynamics of documentation projects. Many project managers assume documentation to be 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 MUST know the meaning of flexibility and the ability to work alone or in a team. 
  • I respond to many people, environments, and attitudes. This experience makes it easy for me to work well with different management styles and personalities.
  • Can they manage me? Even as a freelancer, my remit is contributing to a team. And as a freelancer, I have always been “managed…” by my clients.
  • How would you benefit our clients? If you want me to get involved with client contact, I can help with their needs with knowledge and experience and offer documentation solutions. 

We are also

    • I am confident our considerable Skillset will shine through.
    • Understand issues and be ready to hit 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? 

Maybe you are thinking, how can I shift from contract to perm and take a sharp hit in my pocket? As a contractor, my earnings fluctuated, with no consistent monthly payments due to:

  • The time between contracts (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 we risk takers don’t have holiday pay, sickness benefits, or company benefits.

Pre-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 reinvented my CV every six months.

During the pandemic in 2020, I was out of work from March to October. My company accounts for 2020 saw a £5000 loss and a £3000 loss in 2021.

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

Post-pandemic, IR35 played havoc with the contract market and caused 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. Most calls were for permanent work. 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, one lady, called after finding my CV online and offered me a perm role paying £35K 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 insurances costing a fortune. A permanent role has worked for me and might work for you. Never say never.

What’s the difference?

How many technical writers like me receive calls from agencies trying to source a content writer? It is not uncommon as many writing jobs these days appear under the banner of Content Writer. If you want to choose a suitable writer, read on.

One day, I had to explain the difference between our two titles—comparing my technical authoring skill set to that of a content writer.

Would you know the differences between a content writer and a technical author? If you get it wrong, it will be a costly mistake.

So, what do you know about the following job titles?

      • Technical writer
      • Documentation manager
      • Content Writer
      • Content strategist
      • Content manager
      • Information governance

Technical Writer

First, we have the most comprehensive skill set. We take complex information and make it accessible to people needing to accomplish a task or goal. We must comprehend the process and produce instructions with diagrams.

Before starting a large project, I would ask if they have a strategy identifying the essential documents (the MUST haves). If not, I will create one with a timeline that identifies the production of critical documentation using MoSCoW. Process authors write:

      • Policies
      • Processes
      • Work Instructions
      • Standards
      • How to guide?

We use SharePoint to manage and control documents. 

In the software industry, you can write a wide range of documents, such as

      • user guides,
      • detailed design specs,
      • requirement docs,
      • white papers, and
      • manage a back catalogue of previous records.

Technical Author’s Skill-set

      • Communication skills to write the narrative around the document
      • focussed on detail – without it, the user could make mistakes, or worse, throw the paper away as useless
      • create a consistent process everyone can follow
      • teamwork – impossible to create documents without SMEs
      • technical skills to understand the terminology
      • writing skills go without saying
      • document management,

Document Controller/manager

This role aligns with technical authors; the duties of this role will depend on the industry type. A document manager oversees organisational documents used by employees.

Content Writer and Manager

Content writing produces engaging content for the Web. They’re also responsible for setting the overall tone of the website. Content writers accomplish these tasks by researching and deciding what information to include or exclude from the site.

There are many variations and opinions if you read up on various sites regarding the skill set. These are the most commonly mentioned:

      • Writing skills
      • Focus
      • Originality
      • Research
      • Customer knowledge
      • SEO and
      • Editorial skills

Content Strategist

The job is to create engaging content that resonates with customers and draws. The writer may have significant knowledge of the business. 

Information governance (IG)

IG is a strategy to manage information to maintain compliance requirements and operational transparency. Organisations must have consistent policies and procedures for distributing content. IG lends itself to information security, storage, knowledge management, business operations, and data management.

The differences. . .

Technical and content writers have common goals, such as solid writing and editorial and research skills. However, what the roles create in terms of content are different. Technical writing requires more specific knowledge. The clue is in the title; we produce technical content.

    • Technical writing must be objective and precise, with no personal opinions.
    • Content writing can contain an author’s opinion, figures of style, etc.
    • Finally, technical writers use a wide range of tools for writing, while Google Docs may be enough for content writing.

To get the job done, choose a suitable writer for your project.