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.

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.

 

Navigating Resistance to Change: The Power of Experience

Introduction

As a technical author with 25 years of experience, I have worked with the best and worst of people. I have encountered and survived complex individuals in various roles. 

I possess the ability to perceive people’s reactions to my proposals, which has proven invaluable. Even with my expertise, suggesting a complete transformation and changing the current setup can be challenging.

This article emphasises the importance of continuous change, trusting your instincts, and overcoming resistance to changing established procedures.

    1. The Power of Instincts: Refrain from undervaluing your intuition or gut feelings in professional settings. Your instincts can play a vital role in decision-making. You can identify the best ways to deliver solutions by reading people and their reactions. If it turns toxic, walk away and preserve your sanity and reputation.
    2. Do not overlook the value of experience, a precious commodity. Over 25 years, I have encountered diverse scenarios, learned from success and failure and refined my techniques. My perspective from experience lets me get on with the job and find solutions.
    3. In today’s fast-paced digital world, document management is constantly evolving. New tools, technologies, and methodologies emerge, offering greater efficiency and effectiveness in handling information. We must stay up-to-date with these changes and maintain our relevance in the industry to deliver optimal results for your audience.
    4. Understanding the psychology of words is crucial for effective technical writing. It involves tailoring information to meet your target readers’ needs, expectations, and cognitive processes. Creating content that engages readers requires identifying their frustrations and preferences.
    5. Embracing Continual Progression is the key to staying relevant in a dynamic industry. Remain open to adopting new tools and methods to enhance content creation and management. Change can improve efficiency, quality, and audience satisfaction despite stakeholder resistance.
    6. Overcoming resistance to change is natural in professional environments. Managers refrain from using new solutions because they perceive facing fresh problems. To overcome this resistance, consider the following strategies:
  • Please explain how the proposed changes will benefit the company, including how they will align with business goals, increase efficiency, and improve the user experience.
  • Practical solutions can gain broad acceptance by establishing trust.
  • Involve stakeholders in decision-making, seeking input and addressing their concerns or apprehensions.
  • Provide ongoing support to ease the transition and ensure everyone is comfortable with your solution.

Conclusion:

Your experience as a technical author has given you valuable written communication skills.

  • To introduce changes into a stagnant environment, trust your instincts and keep progressing.
  • Communicate the benefits to stakeholders in overcoming resistance to change and lead towards a more efficient and compelling solution. 
  • Embrace the power of your experience, and let it guide you as you navigate the ever-evolving world of technical authoring.

Technical Authors what we are and what we are not

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.

What I or WE are NOT

Software Developer

If I had proficiency in BASIC, C/C++, Java, et cetera, I would earn significantly more as a developer. I receive calls for API documentation, a skill requiring familiarity with the code.

Project Manager

I will be careful here. I am not a project manager certified through Prince2, Agile Scrum, etc. My PM skills apply to technical documentation, whereby I set my schedule and arrange meetings with SMEs and other stakeholders. 

Beyond documentation, my PM skills do not stretch to:

      • The provision of detailed project planning, including progress evaluation, risk management, issue and resolution. If that is essential, hire a full-time project manager.
      • A secretary organising the working lives of colleagues and taking minutes. I record my meetings (with a dictaphone) and extract the relevant information for the documents.

Technical authoring is lengthy, and additional expectations could delay my progress. It’s time to open the heads of SMEs to extract all that hidden information. I then use it to build a document explaining to your non-technical audience how it works.

While I will be familiar with the terminology, remember I am not an expert in your department. I learn on the job. 

I am skilled in facilitating communication and collaboration through effective verbal and written communication. I provide support and encouragement to help achieve goals, and the process is not as daunting as it may seem.

I’m a third party.

As an external consultant, I decided, after a period of reflection on your situation and expectations, to use MoSCoW. That stands for four different categories of initiatives: 

      • must-haves, 
      • should-haves, 
      • could-haves, and 
      • will not have. 

The “W”, should you prefer, can mean wishful thinking

Let me have it.

When I join, please throw your documentation at me, everything, wherever it is, and let me sift through it all. I have my own Excel spreadsheets to track and control the documentation.

Define how to manage documents/content with SharePoint and Confluence. 

The efficient management of both applications improves the information available to your teams.

By now, I know where the knowledge gaps are where I can improve the documents and start working with your SMEs. 

Project Management 

As mentioned above, I possess the relevant skills within the context of a technical author. 

      • Design new template
      • Improve the structure of existing documents
      • Process documentation across several categories,
      • Arrange meetings with SME’s,
      • I use tried and tested methods to plan, write, review, publish, and maintain the content.
      • Write/update the documents.
      • Procedures and processes updates,

An aid to content development

With over 23 years of experience behind me, I already own an extensive library of generic documentation and various templates. If you have no documentation, we can tweak any document to meet your business profile. It saves not only time but also money. 

ITIL and ITSM

I have experience in producing the following document types: 

      • IT Service Management (ITSM) based on ITIL best practices. Level 1 to 4 BPMN VISIO Processes and Narratives.
      • Service Design, Service Transition, Service Operation and Continual Service Improvement,
      • Delivery and Service Support, 
      • Availability, 
      • Capacity, 
      • IT Service Continuity Management; 
      • Incident, 
      • Problem, 
      • Change, 
      • Release, 
      • Configuration Management and 
      • Service Desk.

Policy and Process

      • Delivering written Policy, Process & Standards
      • ISO27001/9001 compliance documentation to support a company’s GDPRPCI/DSSsecurity project
      • Documentation to support a disaster recovery scenario

Infrastructure Documents

      • Operating infrastructure documentation to support the functions of a large-scale network
      • A documentation suite to help IT teams manage a recently migrated infrastructure.

Editing Existing Content

Enhancements may include: 

      • adding VISIO drawings,
      • new screenshots,
      • reword policies and content per se,
      • additional narrative to processes that are light on information,
      • new templates, and
      • Structure to existing Word documents and consistency. 

All information needs a peer review by people who should know the data best and provide feedback. I leave nothing to chance to get what you need in place. 

Tools

Apart from spreadsheets, MS Word, PowerPoint, and VISIO, my skills keep these projects on track. I will also suggest ways in which you can keep the documentation up-to-date and current. Information is an asset, and without it, you could place the business at a disadvantage.

SharePoint and Confluence

Suppose you have no official documentation strategy or a way to manage the documentation. If so, let me create a plan that will work for you. Documentation must be available to all staff and updated, rewritten, and archived appropriately. Ownership, version control, and historical control are other aspects that need managing.

If the business uses Confluence, my experience on a client site is an overload of outdated content irrelevant to the company. I can analyse all spaces and check when the content was written and submitted. 

Expectations

There are too many to mention, but the immediate impact will be on the following three points:

      • Reduced costs
      • more responsive help desk/support 
      • better informed staff
      • Confidence in performing procedures.

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.

Technical Writing | General Data Protection Regulations

GDPR

On the 25th May 2018, the new General Data Protection Regulations (GDPR) came into force.

Companies outside the EU

If your Company actively trades within the EU and stores, processes or shares EU citizens’ data, then GDPR does apply to you.

Compliance and documentation

One of the primary rules is that under GDPR Process activities MUST be documented.

Companies are required to maintain a set of Policy, Process and Plan (PPP) documentation to ensure you have evidence to support your claims should the ICO investigate any complaint or breach of data.

Note that the Information Commissioners Office (ICO) could demand to see the written documents

What do you need to consider?

As a technical writer, with experience writing compliance documentation, what can I tell you?

If you are still struggling to start

My Blogs are clear, writing one document, when there is a substantial list to be completed from scratch to sign off is a lengthy process. Even if your department has documents that can be reused, it will still take a long time. Compliance projects are manually intensive and documenting GDPR will need dedicated resources.

My experience could be necessary to help you write and manage those documents. The sooner you contact me, the sooner we can start the road to compliance.

  • Create a standard template with – Statement, In Scope, Version Control, Change History, Distribution Lists, Roles and Responsibilities
  • All PPPs must adhere to GDPR – include in the document ‘The purpose of the document’, ‘The Scope’ and add a list of the GDPR compliances relevant to the PPP you are writing and explain the WHY the company are complying along with the HOW the company will comply.
  • The documentation must be relevant to your business. Generic documentation outlining a PPP will NOT suffice
  • Complete the documentation – do not start and leave a document incomplete then sign off; an incomplete document could fail a Compliance Audit
  • Maintain the detail – do not half explain a process or policy
  • Structure the documentation to avoid duplicating information over several documents
  • That the documentation may need to be ISO 27001 compliant

Does Your GDPR Project need documentationClick To Tweet

 

Technical Writing | The risks of poor document management

The risks of poor document management stem from managing multiple types of documents in different formats, workflows and updates. If the documents, which are in constant use have no defined structure it will lead to an uncontrolled and unmanaged repository. This haphazard approach to managing the document Lifecycle impedes employee productivity.

The scenario is this: you are sitting at your desk when your boss requests the latest version of a critical policy document. When do want it you ask?

The risks of poor document management
The risks of poor document management

Now is the reply as she has an urgent meeting. It is located on the company’s shared drive. Your search starts with your department folder.  However, it is not there. You decide to perform a search and type in the title. Your face falls flat when the search returns 100s of potential matches. You open up the most likely and find they are not current.  Panic sets in and your boss is now calling your desk phone, as she is late for her meeting.

We have all been there, as intuitively as we think we have organized our company “shared” network folders, documents get lost and frustration sets in. Whether it is neglecting to archive or delete the outdated version of documents, images, files, assets, etc. or employees using confusing naming scheme for the folder structure – the point is this archaic means of organising and managing documents/assets isn’t working for your company and it is costing you.

Failure to treat business documents as vital assets can lead to:

  • Diminished document utility
  • Decreased business efficiency
  • Increased operational risk and cost

Effective Lifecycle management

The management of Documents continues throughout their useful lifespans ensuring businesses meet compliance and regulatory requirements while preserving the productivity of employees and agility of business processes:

  • Quick access
  • Frequent review and updating
  • Distribution
  • Conversion
  • Archiving

Document management

The risks of poor document management
The risks of poor document management

If your document library is growing with no control consider creating a Document Management library to store and manage your documentation.

The growing influence of ISO and ITIL requires documentation to contain elements which relate to its History, Versioning and sign off, all of which are easy to incorporate. Going forward your staff should know how to manage the documentation in the absence of someone dedicated to the role.

Technical Writing | A brief guide to documentation projects for Project Managers

A brief guide to managing documentation projects for Project Managers will demonstrate that when done correctly will produce long-term benefits.

Here are some examples to help keep your documentation on track.

The original writer is not the best person to check their documentation because they very rarely spot their mistakes.

  • Arrange for a peer review and/or technical review of all changes
  • establish a review process to make sure the documentation is both factually correct and consistent.

All documentation requires ongoing review once or twice a year.

  • If your company use a Document Management system to store documentation, make use of the “metadata” windows to describe the content changes to make the review process easier and consistent.
  • If you are so inclined adding an index to your document, especially when it is a large document will enhance the documents usability

Like everything else, documents become living information that:

  • Maintaining the documentation represents a significant challenge
  • Without a management policy or agreed procedure, the Documentation you are creating will cease to have any value if it is not updated
  • Documentation requires dedicated resources, in which some companies will not invest
  • In other words, use or contract an experienced Technical Writer

Documentation projects, before, during and after

Documentation Projects

Many Project Managers and Subject Matter Experts fail to understand the challenges posed by documentation projects. To lead such a project, you need to know what is important and how you will achieve the goal. What preparations should you make to ensure you complete the project within budget?

Here follows the best advice on the documentation projects, before, during and after.

There are many types of technical and process documentation. If the project is compliance based (PCI, GDPR) concentrate resources on the documentation. Consider hiring a Technical Writer quickly for advice.

Capture the data/content

  • Check the availability of the Subject Matter Experts as well as other team members critical to the project
  • Consider the audience for the documents as that will determine the level and detail of the material.
  • Remember the level of content and information is only as useful as its source and the ability of non-technical audiences to use and follow the instructions/processes

Organise the document and content

Create a standard template with Heading and instructions regarding the level and type of material the TWs need to gather. As a guide use the following headings:

  • Work History
  • Versioning control
  • Scope/Out of Scope
  • Document Purpose
  • Document ObjectiveIntegrate Level 1 to 3 Headings to outline the topics.
    • You can base these decisions according to prerequisite documentation knowledge to provide the master plan for all future written work.
  • Does it require VISIOs/Screenshots?
  • Appendixes

Do NOT waste time creating project timelines to write and produce the documentation.

Until the information and gathering phase begins, do not even consider a guess about how long it will take to complete the documentation.

As the list of titles grows, Management may need to consider extending the budget to finance the project. Abandoning the documentation when it is ‘Nearly there’ will be waste of money, time and resources.

Decide the output format

When the Technical Writer has written the documents, consider which of the following formats will suit the company’s requirements.

  • MS Word stored in a Document Management System
  • PDF stored in a Document Management System
  • *.CHM files created by using such application as RoboHelp
  • Wiki formats: A Wiki provides the user community with the opportunity to provide documentation feedback

Future Review Requirements

Do not overlook the future requirements of any project. All documentation is an ongoing project. Establish a workflow between the IT teams/Process teams and the documentation department to update documentation.

  • Update the documentation when:
  • the IT teams upgrade or modify the Server/Application/technology
  • document all changes, using a change management process to prevent any repeat the configuration
  • align the documentation and the project

Revise the Project

On completion of the project Use the documentation to:

  • reflect the changes and updates
  • test to ensure instructions are clear, concise and correct
  • Avoid considerable time, frustration, and future expense by correctly applying documentation strategies to:
  •  . . . ensure that users can follow the instructions
  • . . . provide a historical record of the changes made during the project

Manage documentation projects before, during and afterClick To Tweet

Technical Writing | The cost of Technical and Process documentation

Why is it that companies view the cost of Technical and Process documentation as an unnecessary expenditure rather than viewing documentation as a centre of knowledge? Management seems to have a blind spot with documentation and conveniently forgets the role of documentation.

Techwriting | Technical and Process Documents

When redundancies beckon, I know how quickly management will sacrifice the technical documentation department. When management seeks layoffs, the technical author(s) will be amongst the first out the door. Months later a member of staff points out that the documentation is out of date and follows up by asking: do we have anything up to date we can use?

In sacking the technical documentation team, no one assumed responsibility. Keeping it up to date is left to those least inclined to keep it up to date. They are the people who would benefit most from its upkeep.

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

Within a software environment, we easily forget that as the developers progress their software application, it also becomes more complex. Failing to supply up-to-date documentation means customers can overlook many of the improvements and advanced features. We could say the same of any IT department. As the network grows, there are more questions and fewer answers. No one has a good overall knowledge of the network because of the lack of documentation.

Where does that leave technical writers?

However, you refer to us, be it technical authors, communicators, documentation staff or as the font of all knowledge. Never doubt our experience, our people skills, our ability to write clear instructions.  We can explain complex technical terms in easy-to-read formats. Who else will put up with blank stares, sarcastic comments and listen to comments such as “whaddya want now?’ to get what your company needs; usable documentation.

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

Remember, it is not about the cost of hiring a technical author. It is about our value to your organisation. Our documentation will keep your staff informed and up to date. There is a point to keeping your processes up to date as your working environment changes. It is also about keeping that software guide up to date enabling your customers to use your product more efficiently and know they invested in a superb product.

Finally, don’t forget that a technical author will not only you save money now but also at a later date and will keep on saving you money, therefore, over the long term justifying their value to your business.

The cost of Technical and Process documentationClick To Tweet