Technical Writing: What’s your view

I have been a technical writer for 23 years. I know my role as a technical writer. However, management can undermine my enthusiasm to deliver a clearly defined strategy due to their lack of knowledge and expectations.

It isn’t a new problem, and despite several attempts to address the problem through LinkedIn and my website, two common issues continue.

      • Management expects a quick return on its budget. and
      • meeting people who think our role is a waste of time,
      • Technical Writing: What’s your view?

Who are we, and what do we do?

Here follows a few prompts about our role:

 

      • 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,
      • our job is NOT 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 are expecting to see results within a short period based on an issue that has continued unchecked for many years, you will be disappointed.

 

There is much misunderstanding regarding the multiple roles technical writers cover withing a business. Many assume we do a cut and paste job and have no idea that writing and managing reams of content is not straightforward. If it were, then companies would not need people like me who can make sense of the problem, offer a solution and complete the job.

 

I make clear in direct terms that our role is vital, and without us, standards of written communications and documentation will forever diminish. Like many technical writers, I am not a one-trick pony as I have other skills which overlap into different roles. We may have one title (technical writer) but have many more titles under our belts.

What skills do you ask? I have worked with many experts and written process documents covering Incident, Change and Problem Management. I have written policy and operational process documents regarding the maintenance of a network. While I may not have the technical knowledge, I could step into a role and manage the network working with technical teams. I also have the following skills:

      1. Business Process analysis
      2. Documentation management (using SharePoint and Confluence and other DMS),
      3. content writing,
      4. process writing.

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
      • don’t 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 our responsibilities.

What do we offer?

We provide a link between the business and the users by helping users to understand the potential of the product.

Knowledge management

if the knowledge resides in the head of a team member 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 anyway!

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 which 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 quality of the documentation. 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 – development is more important

If that is the case, then 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 its 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:

      • 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,
        • 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?

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

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.

Technical Writing | Disaster Recovery Plan

Document the Disaster Recovery Plan

Remember, to be effective you must be prepared to document the plan. Without the documentation you risk the possibility of NOT recovering from a disaster, therefore placing the entire company at risk.

If you have no existing documentation that describes the functions of the company’s servers and their hosted Applications, consider writing relevant Operating Document. In the event of a disaster, without knowing the role and the purpose of a server, as well as the Operating system – it could delay recovery.

A list of your critical systems

All companies will have a set of applications hosted on servers, which, are crucial to the business such as financials.

List your servers by priority and the criticality of the hosted Application – that is the amount of time the server and its applications can remain non-functional before it severely disrupts operations.

Create a disaster recovery plan for each critical system

This returns to the Operating document. To recover the system during a Disaster could take time, more so if the Owner is not available during the disaster to help login and failover the system then failback the system.

Therefore Keep documents simple, direct and to the point and written in such a way that anyone can understand the process, not just the SMEs who designed and built the system.

Who is responsible
Delegated participants must know and understand their responsibility should a disaster happen. Engage them in areas where they will know what to do and act accordingly. When compiling such lists make sure there are Team Leads, and Deputies should the first choice not be available during a disaster.

Make Backups
In this context be sure that if you use allocated drive space that your staff are backing up valuable information and documents to that allocated space.

Do you have an Off-site backup
Store all data in an Off-site Common.

Store Backups off-site in a location away from the same grid as the originals.

Test the Plan
On completion of the written plan, you enter the test phase. Make a plan to failover your infrastructure and then failback the infrastructure.

Take notes along the way to strengthen the areas in the plan which need more validation. Note where there is a need to access backup data time how quickly it takes to restore the system.

Keep the plan safe
Store a paper copy of the plan in a safe place. Remember: during a Failover, the online version could be unavailable.

When it comes to planning your Disaster Recovery strategy, do not forget the disaster recovery documentation. It may be the last project on your mind but could prove to be your company’s one lifesaver.

Disaster Recovery never stops and undergoes modifications every six months or twelve months.

Technical Writing | What is technical writing and why you need it

What is Technical Writing?

Technical writing is a skill and should you hear a Project Manager or Subject Matter Expert say: ‘anyone can write so “why do you need a Technical Writer?” continue reading.

Technical Writing like many jobs has many facets. The fact you see Writer in the job title suggests to the uninitiated that primarily we write. You could not be more wrong! The writing takes only a fraction of the time allocated to the project.

Let’s get to the point

Our time is taken with analysing content and listening to Subject Matter Experts.

Our Writing is concise and to the point. We are not novelists describing a beautiful character down to her laughter lines. A poorly written novel will not hold the attention of a reader; the same goes for poorly written technical documentation. A user wants to read the document and understand say – the function of multiple servers and Operating systems within a significant infrastructure. Know how to follow a process or service within a few sentences. We can create a document from the viewpoint of the reader by listening to the user and offering document(s) based on the best solution.

Technical Writing is – as it explains in the box – technical. We speak to Subject Matter Experts and translate their language into content that a technophobe will understand.

We produce documentation in several formats in such a way, to get the message across to our many audiences. What I have written – you too will be an expert. Give yourself a hand.

Key elements of technical writing

Using a consistent language with regards to terminology.

Creating Glossaries to help readers understand the terminology used within the document.

Formatting document headers with the same font size and tables and drawings labelled the same way are important.

From using Excel spreadsheets, Template creation, document versioning, documentation content and types of material, clear document titles and subjects – working with either a shared drive or a document management system and talking to SMEs every day your average technical author is a ‘rare breed’ indeed.

If you have not already read my post titled “Technical Authors are not easy to find’ we do not attract many candidates.

Technical Writing | Hire a Technical Writer sooner, rather than later

As a Technical Writer with over Twenty Years of experience, I have a question for Project Managers and Subject Matter Experts. Have you ever been involved in planning a project (PCI, GDPR, ISO27001, ITIL) where documentation is critical; if so, how did it go? Crucially, did the project achieve its aims of delivering ALL the documentation? If not – do you know why the plan failed? It could be that you were unable to hire Hire a Technical Writer for advice and guidance.

Why Hire a Technical Writer?

A collective failure of technical / process documentation projects is the lack of knowledge and expertise during the planning and discovery phases. Many project managers and Subject Matter experts fail to grasp the reality of a documentation project. Many projects fail miserably because the planners do not understand the lifecycle of a document. From the initial draft through various reviews and sign-off takes much longer than expected. I regret to say I have met PMs and Consultants that do NOT know the difference between a written process a documented plan and the purpose of the policy. If that is the case, your project could be in trouble.

How long to write a document?

If you ask a Technical Writer how long will it take to write one document, their reply will be – “I do not know”. Technical and Process documentation depending on the project (PCI, GDPR, Operations, ITIL) will have many different requirements and factors which delay the information gathering, the writing and review stages before sign-off.

The likely reality of writing a 30-page document containing:

  • VISIOs (3 or more) comprising between 10 to 30 steps
  • Process narratives (3 or more) of between 10 to 30 steps
  • Appendixes (2 or more)

Will amount to – give or take – at least 8 – 12 weeks of effort before it gets to the review stage. However, the more content the document contains and the more complicated it becomes, the longer it will take.

My advice is not to plan such a project without professional help.

If you are wondering why it takes so long – it is worth noting that compliance projects such as PCI and GDPR generate a lot of documentation. TWs working on large projects could be managing a list of more than twenty documents and every document regarding size and content could be very different.

Hire a Technical Writer

My first word of advice is this – If you have such a plan on the horizon, where the Technical / Process documentation is the primary focus – hire a Technical Writer, not a Business Analyst, to give guidance from the start of the project, NOT when the end date is in sight. The TW can highlight issues, risks and bottlenecks. You will also know what you can reasonably expect to achieve within the allocated time assigned to the project.

The Technical writers will need:

  • a week (at least) to assimilate the project
  • Time for training on any tools
  • access to Subject Matter Experts (SMEs)

Add in contingencies for illnesses, holidays and unplanned absences due to personal reasons and the fact a TW could resign from the project at some point

If the budget and the timelines become fixed (in stone) with multiple documents to complete in a short period, then, consider producing Quality, rather than Quantity.

To ensure quality prioritise, or rank the documents to avoid inconsistency across the documentation set:

  1. Required
  2. Nice to have
  3. Not important

Or use The MoSCoW method.

    • M – Must have this requirement to meet the business needs
    • S – Should have this requirement if possible, but project success does not rely on it
    • C – Could have this requirement if it does not affect anything else on the project
  • W – Would like to have this requirement later, but delivery won’t be this time

Documentation

Who will use them?

  • Documents for external and internal users will require a different level of language
  • What level of information and detail will the audience expect?
  • Does the document need VISIOs?

Additional Points

  • Travel: Will the TWs need to travel abroad or Nationally, if Yes, are they available to go and do they have current Passports/Visas?
  • References: Identify any useable archived documentation.
  • Reviews: decide who will review and who will sign off a document
  • Scope: Could there be any changes which will add to, or change the scope of the project

In summary,

Documentation projects fail due to:

  • poor planning
  • the lack of experience and
  • not allowing enough time to complete the documentation.

Finally: If the success of the project depends on the documentation (Disaster Recovery Plan, PCI/DSS, BCP and ITIL) – why do PMs and SMEs allocate so much of the budget to non-documentation resources?