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

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

Speak Their Language (No, Not Klingon)

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

The Art of Presentation: Smoke and Mirrors

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

Quick Wins: The Fast and the Furious

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

Collaboration: Herding Cats, but With Treats

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

Build Relationships: Be the Office Barista

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

Highlight Long-term Benefits: The Crystal Ball Approach

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

Embrace Technology: The Cool Kid in School

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

Example Scenarios:

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

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

Tales from the Desk of a Technical Author

In the world of technology, unsung heroes lurk in the shadows, wielding their pens (or keyboards) to document the wonders of code, hardware, and software. In my case, training materials, editorial and consulting. Yes, we’re talking about technical authors – the wizards of words, the maestros of manuals, and the unsung champions of clarity in a sea of tech jargon.

Contrary to popular belief, technical authors have a fun job that goes beyond following rules. So, buckle up and prepare to embark on a journey into the quirky world of technical authorship!

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

Do you need help?

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

We’ve got you covered, and fear not; we shall unravel the mysteries of their chicken scratch.

But wait, there’s more! We are:

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

Need a document wrangled into submission?

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

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

And let’s remember our diplomatic prowess. Oh yes, dear reader, technical authors are the peacemakers of the tech world, armed with the patience of saints and the diplomacy of ambassadors. Picture this: a heated debate between rival factions over placing a comma in a user manual. Who swoops in to save the day?

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

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

When you next encounter a technical author, dear reader, consider the depth of their skills and influence as the unsung hero of the tech world. We deliver well-written manuals, crafted templates, and harmonious team collaboration.

 

Technical Author | learn how to project manage documentation projects

As a technical author expert, I recommend that other technical authors should learn how to plan their documentation projects. One of the most common issues project managers face is underestimating the complexity of documentation projects. This can have negative consequences on the project’s success, as inadequate timelines and impossible targets can be set without consulting professionals for advice.

Technical authors, give your career a shot in the arm. Learn how to plan documentation projects. Project managers often underestimate the challenges of projects that involve documentation. This leads to limited success because of unrealistic timelines and targets.

I know the process behind the production of multiple documents. It takes longer than project managers realise. While prioritising other aspects of the project over documentation, they fail to ask a professional for their input and guidance. When the technical author(s) arrive and look at the list of documents and the PM timelines, let’s say you can hear our sighs.

We need clear communications if the PM expects to deliver the entire project. How do you manage 60 + documents? How long does it take to write one document? Have it reviewed, but remember that the document might be out of date further along with the project. Clear communication with stakeholders and team members involved in the writing stages is paramount. The project manager must understand the expectations of the technical author(s) they will work with.

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

Project managers and technical authors can work together to succeed on big documentation projects. However, a technical author to lead might be a better idea and offer better results.

From Contract to Permanent

my transition from contractor to perm

In 2004, while staring at redundancy for the third time, I accepted a six-month contract with BT to fill a potential gap until a permanent role emerged. A former colleague told me that contracting can be a long-term career choice. However, transitioning from a contract to a permanent position can be challenging. He offered various reasons, but I went ahead; I couldn’t afford to be out of work.

trnsition from contract to perm

My first two contracts were with BT in London and their HQ in Ipswich. Then came T-Mobile (now EE), NTTE, and Capita. Before I knew it, five years had gone by, and recruitment agents were calling with contract and permanent jobs. 

However, some agents were reluctant to forward a contractor to a client wanting a permanent technical author. Recruitment agents had stories of contractors accepting a permanent role and quitting after a month (or a week) to return to the contract market. Yet, while I interviewed for several permanent positions, none matched what I wanted.

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

Note: To be a technical author, you need a sense of humour and a sharp wit.

However, I never got to grips with the gaps between contracts. While the money was above average, allowing me to pay myself an inconsistent amount every month. During the 2008 financial crisis, my earnings dropped by a massive 33%, not helped by a four-month contract gap. During that period, Blackberry offered me a permanent role. Unfortunately, I didn’t stay long because of an overzealous  Canadian-based micro-management team leader. So desperate to make her mark, she called me when she arrived at her office in Waterloo, Ontario. She said during one call I must learn to manage my stress. Yet, she caused me stress by constantly interfering and telling me how to do my job—her two years of experience against my 13 years.

Yet, look on the bright side: with more contracts under my belt, I developed more skills: 

  • SharePoint (Document Management)
  • Confluence
  • Help Desk support, transition from contractor to perm
  • policy & process writing, 
  • VISIO process flows
  • ITIL (incident and change management), 
  • ITSM. 
  • PCI/DSS, 
  • ISO 27001 Audits and 
  • operations manuals for data centre migrations and
  • project management

Goodbye to software environments and hello to the broader world of technical authoring. Not only did I widen my experience, but I also travelled to Pune in India, Germany, Belgium, and Canada. 

I have started but cannot finish.

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

A common trend with contracts is poor budget allocation. In one PCI/DSS project, I worked with two technical authors on a 10-week assignment. When we arrived, the PM had used most of the budget to prepare for an audit, which involved hiring an expensive external consultant with high fees.

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

Hiring managers and project managers often struggle with the dynamics of documentation projects. Many project managers assume documentation to be a straightforward task. It rarely works out that way.

On my journey to a permanent role, the points below formed the basis of my decision. If you are a contractor considering a change towards a permanent position, consider what you could offer as a permanent employee.

  • I could concentrate on doing what I’m good at rather than spending gaps and seeking new freelance jobs.
  • Working as a freelancer has allowed me to improve my flexibility and adapt to new situations. Technical authors MUST know the meaning of flexibility and the ability to work alone or in a team. 
  • I respond to many people, environments, and attitudes. This experience makes it easy for me to work well with different management styles and personalities.
  • Can they manage me? Even as a freelancer, my remit is contributing to a team. And as a freelancer, I have always been “managed…” by my clients.
  • How would you benefit our clients? If you want me to get involved with client contact, I can help with their needs with knowledge and experience and offer documentation solutions. 

We are also

    • I am confident our considerable Skillset will shine through.
    • Understand issues and be ready to hit them head-on. 
    • experience of multiple environments
    • recognition of common problems
    • Understanding of project needs
    • broad experience
    • Renewed enjoyment of teamwork

What are you thinking? 

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

  • The time between contracts (a few weeks to a couple of months). 
  • Increasing administration and overheads through my limited company. 
    • unemployment insurance (£150 per month to cover me in case of an injury or debilitating illness),
    • personal and public liability insurance (£10m in value £160 p/a), 
    • private medical for quick treatment (£1200 p/a)
    • accounting fees (£1200+ p/a)
    • Travel costs were deductible; 
      • Car mileage
      • Air Fares between Brussels and Gatwick
      • Hotels and meals while working away from home in the UK
    • Increased Taxation on Dividends
    • The Government fails to grasp that we risk takers don’t have holiday pay, sickness benefits, or company benefits.

Pre-pandemic, I received about five calls a week from agents checking my availability for work. Meanwhile, I maintained a growing Excel spreadsheet of calls listing potential clients and reinvented my CV every six months.

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

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

Post-pandemic, IR35 played havoc with the contract market and caused an enormous drop in calls from recruitment agents. 

Here's a fun fact. In eighteen years as a contractor, I worked at 45 different companies. That doesn't include about ten companies where I walked away after a few days to avoid a disaster in the making.

Why did I walk?

The hiring manager sold me a dud while management expectations were unrealistic..

Between 2004 to 2021 over 300 hiring managers received my CV and more than half interviewed me.

The last journey

In 2021/22, after I completed a long-term contract project, I focused on finding a permanent role. Most calls were for permanent work. The HR department of a County Durham-based bank (my home county) offered me an interview. However, HR rejected me because of my contracting background. So, if you are reading this, take note. I am now a permie, see what you missed. 

transition from contracting to perm

While I had three more interviews, the sticking point was the salary. A business owner, one lady, called after finding my CV online and offered me a perm role paying £35K after a five-minute discussion.

And Finally…

So, when I read the Atkins job description, I thought, let’s give it a go, with nothing to lose. During the interview, the interviewer asked the inevitable question. I refer the reader to the first three paragraphs of this post. 

After quitting the contract market, I am no worse off when considering my salary and the benefits I receive. I no longer worry about tax bills, dividend taxes, accounting fees, and various insurances costing a fortune. A permanent role has worked for me and might work for you. Never say never.

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 | Project Managers and Technical Writers

Project managers and technical writers, two distinct roles. One of my many skills as a technical writer is organisation. We juggle many tasks and switch between them with ease. People skills are important as we speak to coders, engineers, and technicians of various shades. In the meantime, we manage a ream of documentation while taking instructions from SMEs. Occasionally we meet a project manager who has had minimal exposure to technical documentation as part of a project.

techwriting
Project Managers and Technical Writers

If you lack experience planning the technical documentation component of a project I suggest you consult with your technical writer. A working collaboration between project managers and technical writers can help organisations reap the benefits of the project (because it’s documented), and provide better internal and external support through documentation.

If you are one of the many Project Manager who has never worked with Technical Writers, remember we are professionals.  We will not tolerate the viability and quality of the technical documentation to satisfy the needs of others.

Techwriting
Project Managers and Technical writers

So, if you have no direct experience with documentation or Technical Writers consider:

  • Talk with your TW(s) because their experience will provide you with a much-needed background in document management.
  • To help plan the documentation, avoid creating timelines as you progress the project.
  • TAs cannot pull documentation from a hat or generate a document from code.
  • Speak to the TW(s) to gauge how long it will take to review/write/edit a document. In my experience, many project managers overestimate the timelines or worse underestimate the deadlines. Always build in flexibility to allow for problems in the documentation process
  • Reviewing a document intended for transformation containing more than 20 pages plus will take time (the general rule of thumb is one hour per page).
  • The time required for writing
  • Peer reviews
  • Time to have the content technically reviewed

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.