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.

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.

Content and Documents | How Can I help you?

In the aftermath of Coronavirus, many managers may know they have documentation projects in the pipeline and, on their mind, is hiring a technical author. As a contract Technical Author with 20 years plus experience, what can I offer you?

What type of documentation will your project need?

With the documentation, I would advise you NOT to delay even now and start any discovery phase to identify which titles you need to prepare.

How can I make your project run with more ease?

I have a vast collection of generic documentation covering PCI, ISO27001, GDPR, ITIL. Hence, with some tweaks and by understanding your requirements, my generic documentation can be tweaked to suit your company’s needs, which will save time and money.

Compliance projects

Compliance projects generate more documentation than managers expect. If you have not already performed a discovery or due diligence phase, you could have up to 60 titles to write ranked in order of importance.

  • Payment Cards Industry (PCI)
  • ISO27001
  • ITIL and ITSM Policy and process documentation

Confluence and SharePoint

Do you use either confluence or SharePoint, or both?

Have you lost control of the content/documentation?

Has the structure in Confluence been overridden by numerous spaces that are no longer valid, filled with legacy content and no ownership?

Poorly written content and documents can hamper productivity and lead to mistakes. You may need an expert eye to look over your content and documents and identify what is no longer needed and seek to slim down the information in either.

Transformation

Are you about to start a transformation project and have discovered the documentation has no value? Stress not. With help from SME’s and a series of interviews, the documentation will soon be underway. I wrote a booklet on such projects. Read it. To help start the technical documentation, I have the following templates:

  • Operating templates
  • Installation guides
  • Profile document
  • Technical procedures for management

Disaster Recovery and Business Continuity

I have a collection of templates that can help get a plan up and running after consulting with your staff.

Call Me 07534 222517

Email: twriter201@gmail.com

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 | Passive vs Active Sentences

What is a passive sentence?

A Passive sentence is a grammatical voice prevalent in many of the world’s languages. In a clause with a passive voice, the grammatical subject expresses the theme or patient of the main verb – that is, the person or thing that undergoes the action or has its state changed.

http://en.wikipedia.org/wiki/Passive_sentence

Passive vs Active

I can already hear readers asking, what is a Passive Sentence?

Here goes!

Compare these sentences.

  1. The Application is used to collect data (passive)
  2. Use the application to collect data (active)

or

  1. The key was used to open the door (passive)
  2. Use the key to open the door (active)

or

  1. The wire is fed through the box by the electrician (Passive)
  2. The electrician feeds the wire through the box (active)

Using the active voice, sentences provide a clearer more effective message in technical writing and business writing. The active voice identifies the action and determines who performs that work. For clear examples of passive voice look at government documents, which gives the wording a dull, bureaucratic tone.

Over time, writing in the passive voice becomes a habit, one we should all work to change. Of one thing I can be certain, despite the debates, I will continue to use the active sentence.

Technical Writing | Technical documentation vs Helpdesk

Technical Writing | Interviewing SMEs

One of the many skills a technical writer needs is the ability to form relationships with SMEs. An experienced writer talks to subject matter experts to gather insights for a document. Without their input, the writer will face difficulties producing documents. On one project, I worked with two technical writers. They had their styles of approach, and I have mine.

One of our team members, x,x, had a style and approach that rubbed many SMEs the wrong way. I have a laid-back approach. If the SME could not talk because of urgent work, then that’s fine—we can reschedule the conversation. X.X found it difficult to communicate with technical SMEs, which made it challenging to gather the information. He had never worked in the technical field coming not from a technical background, but a process background where people are polite.

Approaching and Interviewing  SMEs 

  1. Ensure you schedule a meeting with the SME in advance. Please do not turn up at their desk and expect to talk.
  2. If you collaborate with other technical writers, review the project plans and inquire whether they have contacted the subject matter expert (SME) regarding topic XYZ. If they have, verify the information is what you need. In such cases, refrain from requesting the SME to reiterate the information.
  3. I use a dictaphone to record interviews because I can always run the recording back if I have any queries. To date, no SME has objected to me recording the conversation.

    approaching and interviewing subject matter experts
    approaching and interviewing subject matter experts

    • If they DO, it will mean listening intently and writing the information
  4. Approach the Interview at the appointed time:
    • Do not be surprised if the SME cancels the meeting because of other demands,
    • If so, reschedule the meeting
  5. Always regard the interview as another knowledge-capture exercise that adds to your experience. Do not assume you know everything before you get there, even if you do.
  6. The SME will assume you understand their language; if not, stop the interview and request a less technical explanation or reassess your ability to do the job if you still do not understand.
  7. Schedule only an hour for the interview, but be clear that you will need to reschedule more time if specific points are unclear.
  8. Be transparent – there will be a peer review required, but you will let them know in advance when the document is ready for review
  9. approaching and interviewing subject matter experts
    approaching and interviewing subject matter experts

    If the SME is not aware of your role or why you need their comments to introduce the project, and if you have not already done so, introduce yourself

  10. The SME may not know everything and will refer you to another SME for information
  11. When you return to your desk, start writing the document. Do not wait for a few days, even if you have recorded the interview.
  12. Carry a pad and pen. You may need to ask the SME to draw the infrastructure.

Technical Writing | Professional vs Amateur, its a matter of choice

A LinkedIn connection shared a poster, which read: Professional vs Amateur; If you think it’s expensive to hire a professional, wait until you hire an amateur.

In 2004 I had an interview in Watford and later Cambridge with software companies looking for a Technical Writer. During the second interview, I had this feeling of deja-vu in that it followed a similar line to the Watford interview. The hiring managers seemed uncertain. The feedback was both companies appointed an internal resource to save money.

Later that year the Watford company after a management buy-out sacked the TA because the documentation failed to meet standards. I was later contacted by an agent after the Cambridge internal appointment failed to deliver.

A previous client called as one of their technical writers had left with work to complete. Once I analysed the work, I made it clear that I had no time to rewrite the work. The manager to keep costs down employed ‘technical writers’ with negligible experience on a high-profile project for a major Telco client.

I can appreciate the fact when times are tough companies like to make a few savings. However, the difference between employing a professional vs. amateur can be stark regarding cost.

Professional vs Amateur, it’s a matter of choice

What you need to consider is the result. Do you want a professional job or a makeshift effort by an amateur? Many experienced technical writers will point out that you get what you pay for. My advice is to be ready to pay the going rate to attract an experienced technical writer who is more than capable of doing the job. In terms of time and delivery, it will save you a lot of time and energy and negate the need to pay twice for the same job.

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.