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. 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.