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 phone calls from agencies trying to source a content writer? Over the last few years, agents and interested parties have asked me to compare my technical authoring skill-set to that of a content writer. Do you know the difference to choose the right writer for a large project?

If I asked you to look at the following jobs titles, would you know the difference?

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

Technical Writer

We are many things to many people; 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. If not, I will create one with a timeline that identifies the production of critical documentation using MoSCoW.

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

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

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

Content Writer and Manager

Content writers 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.

Document Controller / manager

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.

The role of a DC and a technical are closely aligned.

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

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

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.

Project Management and Doucmentation

The quality of project management has a direct impact on technical documentation, a fact project managers overlook . This article looks at the areas where the relationship between project management and technical documentation intersect. 

Put a plan around a project or a project around a plan

Technical documentation will suffer if the project is floundering without a project plan. A document project without a plan is always at risk of failure. There is a tendency by those with no documentation experience to change the goalposts and and add to the project because in many cases they did not listen to the experience and advice of their technical Writer. 

While documentation cannot compensate for the lack of a plan, it can help to revive a troubled project. This method of catching up through documentation will extend timelines, but will serve the project better by mitigating risks and strengthening the overall product through documentation analysis.

Frustrated

An experienced technical writers can certainly find their frustration peaking when the project timeline isn’t workable, or the Project Manager fails to listen to advice. THis happens when:

  • working with staff members who have no experience working with documentation and assume its an easy straightforward task
  • unworkable deadlines that sacrifice documentation quality and lead to frustration among internal parties

It is worth bearing in mind the following: 

  • when scheduling technical documentation tap into the TAs knowledge to help plan the timeline for documentation.
  • Writing or migrating content is not an instantaneous process; a failure to work with the writers could led to counter productive problems. 
  • If the timeline is genuinely tight, develop a list of documentation priorities in order for users to adopt the product.

A typical breakdown for a technical writing project includes:

  • Research time to learn the project and other elements, such as the underlying technology and related issues required for the documentation effort.
  • Dedicated time for writing.
  • Dedicated time for editing. copy editing and editing for style, clarity, and other issues.
  • Dedicated time to review the technical accuracy of the documentation. Never assume that a document is correct. Always create review time for accuracy by SMEs.

Allow sufficient ramp-up time

Technical writers need sufficient ramp-up time to become versed in the product. While ramp-up time is relative depending on the writer, a project manager can support the writer:

  • Provide ready access to necessary hardware and software so the technical writer doesn’t have to waste time waiting on equipment required for documentation projects.
  • Provide the necessary system access, usernames, and passwords.

Allow technical writers ramp-up time is more than a learning curve; it’s having the resources in place so they can perform their jobs with minimal downtime, which is billable when they are on-site waiting for corporate bureaucracies to deliver the resources they need.

Review the reviewers

While technical writers must have a stake in the technical accuracy of the documentation they produce, there is often a need for technical reviewers to review the documentation. Take into account this review time  in the overall project schedule, including:

  • Scheduled time for technical staff, project managers, and other reviewers to go over the documentation.
  • Time for the technical writers to add the revisions to the documentation.

Can project managers and technical writers get along?

The documentation component of a project requires input from technical writers to help ensure quality technical documentation. A working collaboration between project managers and technical writers can help organisations reap the benefits of better design (because it’s documented), and better customer support through documentation. A self-sufficient customer who doesn’t call customer support is like money in the bank for your company.

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