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)

Technical Writer needs a new direction

I need a new direction. I am a senior level Technical Writer/Content Writer who has managed medium to sizeable Technical Documentation projects.

I am looking for companies that require an individual to maintain their Technical Documentation, but cannot afford to employ a technical writer full time. Any arrangement will be on a contract basis for a fixed period.

My original Technical Writing background was in Banking and Retail Software. I later worked in specialist fields including Operations (data Centres), ITIL, ISO and PCI.

My extensive experience includes OFfice365, SharePoint, VISIO and Adobe applications.

If you would like to speak further regarding your documentation requirements, please contact me.

Michael Clark

Technical Writing – The Survivor’s Guide

This book Technical Writing – The Survivor’s Guide is available through Amazon in paperback and Kindle format contains all the Blogs I have written since 2012.

If you want to know how we work, estimate a project, how we view project managers and our role go ahead. Make my day and buy a copy.

Technical Writing – The survivor’s Guide

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. 

The most excellent technical writer

As a Technical Author, one question an interviewer asks is what makes a good Technical Author? Based on my 23 years’ experience here is my take on what makes either a poor, a good or an excellent technical writer.

Poor technical writers edit the content and leave it at that. There are no questions, no curiosity even when a set of instructions do not read correctly. In which case, if that is you start looking for a new job.

Good technical writers :

  • Logically set out the steps starting at A and avoid no detailed Work Instructions leading to Step Z.
  • Methodically test the steps
  • ensure the content is easy to read and understood by reviewers
  • They know their ABCs

Excellent technical writers go a step further – we:

  • ask the question of why – who – what – when – where and how
  • analyse the problem the user is experiencing  
  • ask how the documentation will solve the problem
  • anticipate the issues users could encounter and the questions they will ask when they follow the material.
  • Build relationships with teams across the floor
  • Use humour and diplomacy to get what we want
  • Pretend we are a user reading the document for the first time
  • include links to related topics to keep the user briefed

All of the above takes time, effort, and creative thinking but as excellence is a byword we never feel the pain.

By covering the above points, the documentation will impact positively on the business. Excellent documentation increases user adoption, reduces the impact on your Support services, and aids your staff should a problem occur that could damage the company and its reputation.