Technical Authors what we are and what we are not

Whatever your view of a Technical Author, do not be fooled by that title. We are much more than people realise, and we can help in ways you never thought possible. So, let me bust the myth about what we are and what we are not.

Would you mind reading on? 

What I or WE are NOT

Software developer

If I knew BASIC, C/C++, Java, you know where I’m going, I would be earning far more as a developer.  I receive many calls for API documentation, a niche skill requiring knowledge of the code used in an API.

Project Manager

I will be careful here. I am not a project manager certified through Prince2, Agile Scrum, etc. My PM skills are relevant 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 do record my meetings (with a dictaphone) and extract the relevant information for the documents.

Technical Authoring on its own is a time-consuming role, and any expectations from me over and beyond the documentation scope of the project might be pushing my ability to get things done in a timely matter. Remember, our skill is documentation and how to fill those documents with information. 

I can 

Sit with your SMEs and open their heads 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 do supply effective written / verbal communication and collaboration, sympathy and encouragement to get things done. It isn’t as painful as people think.

I’m a third party

As an external consultant, I make decisions after a period of reflection on your situation and your expectations using 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.

While I am at it, I suggest analysing SharePoint and/or Confluence and define exactly how your teams will manage the documents/content. 

The efficient management of both applications improves the flow of 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 do possess the relevant skills within the context of a Technical Author. 

      • Design new template
      • Improve 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 the profile of your business. 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 suite of documentation to help IT teams manage the pre-migration and post-migration stages of a Cloud-based service program.

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, 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 means of managing the documentation. If so, let me create a plan that will work for you. Documentation needs to be available to all staff and needs to be updated, rewritten and archived appropriately. Other aspects that need managing are ownership, version control and historical control.

If the business uses Confluence, my experience is an overload of outdated content no longer relevant to the company. I can analyse all spaces and check when the content was written and submitted. 

Expectations

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

Get a head start

Templates with generic content

Do you have a documentation project lurking in the background and you are yet to get to grips with the detail? I have available many templates which contain generic policies, processes, and standards content relating to the following documentation:

      • PCI/DSS
      • ISO27001
      • ITIL
      • ITSM

If you are embarking on a project for any of the above from scratch, you can save time measuring into months by using the relevant template.

Consider the fact it can take upwards of six weeks to produce one document of between 20 to 30 pages, imagine the scale of the work if you have more than sixty titles to write from scratch.

The content within the documents will require tweaking to make them relevant to your company, such as Team names and Team members, Technical terms and branding.

However, be aware I do not own a comprehensive list of Policy and Process documents. My library covers the documents that will take time to produce.

VISIOs

I own VISIO drawings covering the following and many more:

      • Incident management
      • Change management
      • Problem management
      • Document lifecycle

Templates with Headings only

You may require a set of pre-headed templates to help you document your Network. You can use these templates to document your servers and use the documents for many purposes.

Training: help new starters gain knowledge about the Network.

Audit: Have to hand information that can help you manage your Network over the long term.

Data Centres: Use the templates to plan a data centre migration.

      • Operating documents
      • Installation guides
      • Profile documents (5-Pages)

The difference between Policies, Standards, Procedures and Strategies

Over the years I have written many policies, processes. strategies and standards and related documents.  These documents outline how a business operates and help when a team member requires a reference. so to answer a question: what is the difference between policies standards procedures and strategies?

The agony point for me is when a professional consultant does not know the differences between the document types and refers to one as another, the other as another and cannot grip the function of a specific document. In the meantime, steam billows from my ears while the consultant continues to sprout opinions on the various documents.

For the uninitiated here is my explanation of the difference between Policies, Standards, Procedures, Standards and related documents.

Policy document?

A policy sets out an agreed management policy which might refer to IT Security and Risks. However, it will not give any direction on how to execute this vision or strategy.

A set of policies are principles, rules, and guidelines formulated or adopted by a Business to reach its long-term goals. Policies are signed off by management and published in the Company’s preferred medium.

The writing of Policies is to influence and determine major decisions.

Processes and Procedures are the specific methods used to express policies in action in the daily operations of the Business.

What is a Process

It is a task, a procedure – it is NOT a Plan.

The ISO definition of a process is:

A process is a set of inter-related activities that turn inputs into outputs’

You MUST learn the process; know WHY you need it and How to perform the process end-2-end.

  • Process a high-level description of a series of inter-related tasks covering an entire business.
  • It is an internal, ongoing process that must be updated as per Policy guidelines
  • serves as a crucial guide for employees and managers.

Procedure 

A procedure contains more detail than a process but less detail than a work instruction. It tells users HOW to perform a series of sequential tasks to achieve a specific outcome.

Participants will complete a procedure from start to finish in one continuous time frame (no significant delays between steps).

Work Instructions (WI)

A WI contains a detailed description of a task. Its sole purpose is to explain step by step how to do a specific task.

Plan

IT IS NOT a Process

      • Organisations have Management Plans which outline WHAT you are going to do, it does not explain HOW you will perform a task.
      • The Plan determines precisely how resources are to be allocated and provides backup plans if resources are not available at a crucial time.
      • The Plan document outlines what components must be included to demonstrate How a process will work.
      • A plan is how you will move from A to B and should support your strategy by providing a method to reach B containing an acceptable balance of risk and reward

What is strategy?

A strategy document explains the strategy – how an organisation will move from point A to Point B

      1. How will you get there?
      2. Issues, problems
      3. Solutions and tools to get you to point B

A strategy is a solution to move from A to B taking into account any unforeseen issues and problems that may occur to slow your journey to B.

Your strategy is WHAT you want to do

Understanding the difference between a strategy and a plan allows you to make useful strategic planning decisions that separate the two.

What is the standard?

Standards are mandatory actions or rules that give formal policies support and direction. One of the more difficult parts of writing standards is getting a company-wide consensus on what standards need to be in place. This can be a time-consuming process but is vital to the success of your information security program.

      • Used to indicate expected user behaviour. For example, a consistent company email signature.
      • Might specify what hardware and software solutions are available and supported.
      • Compulsory and must be enforced to be effective. (This also applies to policies!)

Choose the right Writer

I wonder how many technical writers like me receive calls from agencies trying to source a content writer? It is not uncommon. Many writing jobs these days appear under the banner of ‘Content Writer’. If you want to choose the right writer, read on.

One day I had to explain the difference between our two titles. A comparison of my technical authoring skill-set to that of a content writer.

If you were asked, or you were seeking a writer—do you know the difference? If you get it wrong it will be a costly mistake.

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

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

Technical Writer

Firstly we have the widest skill-set. We take complex information and make it accessible to people who may need to accomplish a task or goal. We need to understand what can be a complicated process and write detailed instructions, including process diagrams (PCI, ISO, ITIL, GDPR).

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

        • Policies
        • Processes
        • Work Instructions
        • Standards
        • How to guides

In addition, we have document management skills working with an application such as SharePoint to manage and control the documentation. .

In the software industry, you could be writing a wide range of documents such as:

        • user guides,
        • detailed design specs,
        • requirement docs,
        • whitepapers, and
        • manage a back catalogue of previous documents.

Technical Author’s Skill-set

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

Document Controller / manager

This role aligns with technical authors; the duties of this role will depend on the industry type.  A document manager is responsible for control, security, accessibility, and review of organisational documents used by employees, such as policies, procedures, guidelines, forms, templates, and training materials.

Content Writer and Manager

The aim of Content writing is to produce engaging content for Web material and later with experience manage the pages and ensure content connects with their audience. They’re also responsible for setting the overall tone of the website. Content writers accomplish these tasks by researching and deciding what information to include or exclude from the site.

If you read up on various sites regarding the skill-set, there are many variations and opinions. These are the most commonly mentioned:

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

Content Strategist

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

Information governance (IG)

IG is a strategy to manage information to maintain compliance requirements and operational transparency. To work correctly, any organisation must establish a consistent and logical framework for employees to distribute content through their information governance policies and procedures. IG lends itself to information security, storage, knowledge management and business operations and the management of data.

The differences. . .

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

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

To get the job done choose the right writer for your project.

Technical Writing: What’s your view

I have over 23 years of experience as a technical writer. My enthusiasm to deliver clearly defined documentation/content strategy has never diminished. Yet, two common issues remain:
  • 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 writer, but I have many more job titles under my belt. What skills do you ask? I communicate with many experts and produce relevant documents, namely 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 working with technical teams. 

What can I tell you?

  1. 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,
    • We can analyse workflows and write complex processes with drawings to help teams work more efficiently,
  1. our job is never straightforward as we rely on many factors that hinder progress,
  2. A change to one document means changes to related documents that contain exact content,
  3. 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?
  1. 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.
  1. 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 have no idea 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.
  1. What do we do?
I have worked with developers, engineers (of varying shades) and IT subject matter experts. 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 provide a link between 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, etc.
      • 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 up to date and compatible with their version, you will hear the complaints loud and clear. There is also, in many cases, a clause contained in the Ts & Cs that explicitly makes clear the business will provide documentation. Relax at work! We don’t get much 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.
There is a high level of stress factor involved in this profession due to uncommunicative team members and unrealistic expectations whereby 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 in advance of deadlines to make the required modifications.
People assume technical writers only write and think it’s an easy job. The importance of technical writing will come when they understand the following:
  • The actual work a technical writer does,
    • we utilise other essential skills,
    • 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:
  1. An SME rarely has time to produce the documentation and has other priorities,
    • your SME may be a good writer, but that does not an excellent technical writer make,
    • they leave gaps in the content because they don’t think it is worth a mention.
    • If so, a technical writer will revisit the documentation and test for gaps and add the missing content,
  2. 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.

A virus made us do it …

Are you one of the many who during lockdown has wondered what the future may bring? Do you have a clear vision of what is personally meaningful and how you will change your life once the pandemic ends? 

Depending on your point of view lives will change either for the better or poorer.

I’ve thought a lot about what should change and here follow my thoughts on possible future events?

Government has learned a huge lesson and that is when a crisis looms act immediately. 

If businesses prepare for events, disasters and business continuity, why is it the government had no pandemic strategy. The government needs an effective strategy tried and tested at least once a year. Perfect preparation prevents poor results.

The UK needs to reduce its dependence on international supply chains and be ready and capable of producing what we need when we need it. Self-sufficiency.

There is a contamination risk stockpiling PPE in enormous warehouses, rendering the material unusable. As part of a pandemic strategy, the government requires a continually updated register of businesses that could shift production in a matter of days to keep the UK supplied with the PPE equipment. 

When the government negotiates BREXIT, there is much to consider, such as our diminished skills base. We need a comprehensive state-funded education program to train engineers, plumbers, electricians, construction experts, agriculturalists and many more. We don’t need a constant stream of graduates with non-degrees.

Britain is open for business allowed foreign competitors to buy many of the UK’s biggest household names (ICI, Cadbury’s, Boots, Pilkington Glass) and later move operations abroad, denying the exchequer billions in lost revenue. Smaller UK manufacturers closed as there was a cheaper version somewhere in the world. 

While protecting companies from foreign intervention is not government policy, we need to rebuild our industrial base to lessen our dependence on markets outside the UK. If not, what happens if we need immediate access to vital goods and discover we can’t purchase any because of global demand?

People and businesses will demand cash to save their businesses, although many were on the verge of collapse. The government must focus on what will thrive and benefit the UK economy. 

 Not only will the NHS receive more cash, but also the Police and education. I suggest the NHS needs reform because, without it, the entire organisation becomes a financial vacuum. 

Pollution levels have dropped. Step outside and look at the blue sky. How fresh is the air? Also, I live below the flight paths to Heathrow and Luton, and there are no visible vapour trails in the sky. 

 Now we have a feel for a cleaner world, what are we going to do about it?

We could start with substantial investment in developing electric cars and renewable resources. If we plan to buy electric vehicles, don’t forget the investment needed to design and build the infrastructure required to charge up all those automobiles. The casualties would be the oil-producing countries who would lose vital revenue. Let’s not forget the government would lose billions in tax on fuel sales. Going green will be great for the planet, but the government will raise taxes. Talking of which…

… I foresee the government hiking PAYE and corporation tax by up to +-7% to claw back the money it spent during the pandemic. There may be very little hiding room for corporations who have evaded paying their ‘fair share’ since 2008. However, when raising taxation, the government treads a thin line. Tax is a sensitive issue and will not please many Tories, although I can’t see Labour having a problem with such actions. 

As for Future holidays, it will be a staycation. I recommend a fortnight in the West Country. The airline industry may take years to recover, meaning fewer and more expensive seats owing to high profile failures (As I write this, I hear British Airways is making 12000 staff redundant).

The Office Culture

Many businesses allowed their staff to work from home. It would not surprise me if CEOs and Directors had discussed with HR that possibility in the past, but didn’t allow it for productivity reasons. By now, I’m sure many CEO’s, jobsworths, and bosses have realised their business can operate and not suffer without the staff at desks. 

Could home working become the norm?

Canny CEOs could slash company costs and decentralise their London operations to either satellite offices or branches. Doing so will give the CEO access to more applicants who wouldn’t move to London. It will be a significant benefit to Employees who rise and shine, have breakfast, and sit at a desk in their home, or maybe work closer to home on a short commute. 

Although it would be an immense change, it would not surprise me if the company bosses a few years down the line sought to cut salaries as staff no longer travel into work? 

On a personal note, by not travelling to London I’d save the following every week:

  1. train fares (Oyster £75.50)
  2. driving to Amersham parking (30 miles round journey; 5 X 6miles)
  3. parking (£36.00)
  4. lunch and coffees (£60.00; 2 X Coffees and lunch of £6 per day)

I acknowledge that not everybody can work from home. Employees of the NHS, emergency services, hospitality, retail and transport services will always be in the ‘office’. However, with trains and buses carrying fewer commuters, there will be more room available. Tourists will find it easier to use the London Underground to visit tourist attractions.

House Prices in London: 

If large companies decentralise their operations away from London, or any major city, house prices would drop. Who wants to live in London when the same well-paid opportunities are available outside London in locations with higher standards of living.

So, here follow a few final thoughts.

  1. If fewer people move to London, could it solve the question of affordable housing?
  2. Less congestion on the roadways and motorways means less damage to the roads and fewer accidents,
  3. with lower pollution levels, the NHS will see a decline in patients with respiratory problems.

The above are my views, and there are many more I could add. No doubt readers will point out their thoughts. I believe change is coming, like it or not. Much will depend on how we, as citizens of the UK, decide we want to move with the changes. 

Content and Documents | How Can I help you?

During this pandemic, were you in the process of hiring a technical writer to help with your content and document requirements? To support the work already completed were you were on the brink of hiring a technical writer.

When it comes to 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 ease?

I have a vast collection of generic documentation covering PCI, ISO27001, GDPR, ITIL. Operating Document templates for migrations of hardware and also useful for audits. 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 tend to 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 or bin the information contained 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. You might want to 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: [email protected]

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 | Interviewing SMEs

Subject Matter Experts (SMEs) are essential to enable you the technical author to write that document. Without their input you will struggle. So, how does an experienced technical writer consider approaching and interviewing SME?

I base my advice on my personal experiences of talking to and working with SMEs. You will no doubt find, like me, that some SMEs are difficult while others are happy to help.

Approaching and Interviewing  SMEs 

  1. Make sure you schedule a meeting with the SME in advance, do not turn up at their desk and expect to talk. Most SMEs are busy and might work on an important task.
  2. Make sure you know the SMEs area of ability and their role within the company
  3. If you collaborate with other technical writer’s check any project management plans or ask if they have already spoken to that SME
  4. If yes check the information to see if it applies to you. It will save time asking the SME twice for the same information and prevent any stern reminders that they have already discussed ‘XYZ.’
  5. I use a dictaphone to record interviews because it means if I have any queries I can always run the recording back. 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
  6. 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
  7. Always regard the interview as another knowledge capture exercise, which adds to your experience, do not assume you know everything before you get there, even if you do.
  8. The SME will assume that you know what they are talking about; if not – stop the interview, and either request a less technical explanation or if you still do not understand then you need to reassess your ability to do the job.
  9. Only schedule an hour for the interview but clarify that if there are any points which are not clear, you will need to reschedule more time
  10. Be clear – there will be a peer review required, but you will let them know in advance when the document is ready for review
  11. 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 you if you have not already done so introduce yourself

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