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

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

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.