Featured

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!)
Featured

Choose the right Writer

I wonder how many technical writers like me receive phone calls from agencies trying to source a content writer? Many times I have had to explain the differences to an agents s they don’t know there is a difference. This article compares my skill-set as a technical writer to that of a content writer.

Do you know the difference?

Read the following jobs titles, would you know the differences in their skillsets to enable you to make the right choice for a contract?

        • 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 the ability to understand technical concepts and 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.

Featured

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.

Featured

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
Featured

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
Featured

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.

Featured

Technical Writing | Sourcing a technical writer

When sourcing a technical author, ensure their experience matches your requirements. You need to source one who has the right knowledge, background and expertise. At the interview, they should talk through that experience; if not keep searching until you do.

Productive years as a Technical Writer

An experienced Technical writer can only be an asset to your team or project. The longer their tenure, the broader and more in-depth their experience will be. However, the only way to be confident is to read their CVs carefully.

Do they use Social Media or have a website?

Check out LinkedIn for their profile; If you cannot find one or a website describing their experiences, what have they be doing?

During the interview, did they communicate?

During an interview be wary of a candidate who sits, listens, and says very little. An experienced TW will respond to your questions and may offer suggestions on how to elevate the project with innovations you may not have considered.

Read the CV and be prepared to discuss the project. I have arrived at an interview to find the interviewer has not read my CV. I have a simple rule regarding my experience; if you cannot see it on the CV, then I have not done it. That does not mean that I will turn down unfamiliar tasks.

Effective communication

An essential part of our job is the ability to communicate with SMEs to gather the right level of detail for the documentation. If the documentation appears vague, it might be time for a chat.

Do you want a contractor or permanent TW?

You may build a team, and you need a Technical Writer to keep the documentation up to date; a person who will grow into the environment. However, I would caution against using a Technical Writer permanently unless you are sure there will be ongoing work.

Work cycles can dip, so be careful how you use the Technical Writer.  During one of my earliest contracts, the project engineer referred to me as a secretary and treated me as one as did the rest of the team. In a much earlier role, my line manager used me to shift boxes and to clean the stock room and a general dogsbody.

A proactive Technical Writer between writing, researching and interviewing could improve the company’s documentation. However, once they get on top of the tasks, the role could become routine and repetitive. There will be the odd spurt of activity within the working life cycle; hence, why the position of Technical Writing lends itself more so to contract work rather than permanent work.

To summarise: if you use a permanent Technical Writer ensure you have plenty of contingencies within their job. To avoid your TW developing itchy feet, I would suggest that you discuss additional tasks that may add value to their experience. Allowing a member of staff use them for jobs, which an office junior should cover will not go down too well.

A word of caution

Unfortunately, our profession can attract its fair share of triers. You can reasonably expect CVs from candidates who have had minimum experience preparing ad hoc documentation. Unfortunately, that minimal experience will NOT be enough to perform the job.

Many recruiting agents have a minimum expertise sourcing Technical Writers. When they speak to prospective candidates, they hear a few buzzwords and place candidates forward for a role for which they are not suitable. Be sure to check that they have the right experience and background.

Applying the following advice may help you avoid problems:

Be careful hiring a Junior Technical Writer or one that has worked in a permanent position for the last five years.

Why: a permanent position can be very repetitive, which means the Technical Writer’s experience may be severely limited. That also goes for junior writers, for high-profile projects hire a seasoned contracting professional, who can talk through the project with you. In my experience, there is a world of difference between a contract Technical Writer and one who has chosen permanency.

Finally, budgets – ensure you are buying the experience you need. In the world of Technical Writing, the price you pay determines the standard you buy. By using the wrong candidate could be a costly mistake.

Where else can you source a Technical writer?

If you prefer to source a Technical Writer, you have found me. However, I may not be suitable for the role. Check LinkedIn, Social Media sites and the online Job Boards. Ask other companies and fellow professionals if they have used Technical Writers and if so, what was their experience. They may have recommendations which in the long run could save you money.

Featured

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.

Featured

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.

Featured

Technical Writing | Technical documentation vs Helpdesk

technical documentation vs helpdesk
technical documentation vs helpdesk

Technical Documentation vs Helpdesk – Despite the reluctance to invest in technical documentation, many managers bypass a proven way to cut back on calls to the Helpdesk. No doubt many helpdesks provide an excellent service and manage the demands of the users. The problem with most technical documentation including user guides is that it is incomplete and full of gaps. Documentation needs to flow and provide practical tips on how to get the best from the software.  If your customers had well written and comprehensive documentation you could substantially cut back on costly calls to your helpdesk.

Technical documentation vs Helpdesk

technical documentation vs helpdesk
technical documentation vs helpdesk

I have experience in manning a premium line Helpdesk and have spoken to many angry customers whose subjective complaints about the company and the guilty software lead to comments such as:

  • The product is bordering on rubbish, and it doesn’t work, is it bugged?
  • annoyed with the company because the software is garbage
  • I can’t follow the user guide because it doesn’t belong to my version of the software
  • I can’t follow the instructions

When documentation fails to deliver the answer, the Helpdesk records a steep curve in calls. Customers who feel forced to call the Helpdesk Support can hold mixed feelings about the product and company.

Frequently Asked Questions (FAQs)

technical documentation vs helpdesk
technical documentation vs helpdesk

Customers are the lifeblood of any organisation, and their demands can vary.  To facilitate their requirements, I created a feedback option to enable internal and external users to point out where the documentation appeared vague.

The developers and helpdesk provided a more detailed solution based on their knowledge and experiences. I created a FAQs knowledge base (or Wiki) for external users and placed the information in the back of the document. The internal staff received the content via a RoboHelp *.chm file.

The FAQs were a success and helped cut calls to support by 80%. I had created searchable information that was easy to find and accessible to all staff.

Experienced technical writers can produce audience focussed documentation that helps customers maintain productivity.

Technical documentation vs Helpdesk

Always treat your documentation and your information as an asset’ and invest in the necessary resources maintain the documentation. The savings could be significant meaning satisfied customers.

Featured

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.

Featured

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?

Featured

Technical Writing | A brief guide to documentation projects for Project Managers

A brief guide to managing documentation projects for Project Managers will demonstrate that when done correctly will produce long-term benefits.

Here are some examples to help keep your documentation on track.

The original writer is not the best person to check their documentation because they very rarely spot their mistakes.

  • Arrange for a peer review and/or technical review of all changes
  • establish a review process to make sure the documentation is both factually correct and consistent.

All documentation requires ongoing review once or twice a year.

  • If your company use a Document Management system to store documentation, make use of the “metadata” windows to describe the content changes to make the review process easier and consistent.
  • If you are so inclined adding an index to your document, especially when it is a large document will enhance the documents usability

Like everything else, documents become living information that:

  • Maintaining the documentation represents a significant challenge
  • Without a management policy or agreed procedure, the Documentation you are creating will cease to have any value if it is not updated
  • Documentation requires dedicated resources, in which some companies will not invest
  • In other words, use or contract an experienced Technical Writer
Featured

Technical Writing | Why your business needs Technical documentation

Managers underestimate the purpose of technical documentation until they discover they have no relevant documentation. Listed below are 6 reasons why you need technical documentation

  1. Without technical documentation you have no historical record of any project ever completed within the company
  2. You have no metrics against which to measure current projects
  3. You have no information which outlines the lessons learned and the lessons failed
  4. During an upgrade project the team relies on guess-work to get things right . . . it also means the project will take much longer to complete stretching the budget
  5. What documentation there is lies scattered over several drives and only makes sense to the author
  6. Your valued tech staff have left the company taking information with them in their heads

Now you know why Technical Documentation is important; if you recognise one or more of the points above . . . what’s your next move?

Featured

Documentation projects, before, during and after

Documentation Projects

Many Project Managers and Subject Matter Experts fail to understand the challenges posed by documentation projects. To lead such a project, you need to know what is important and how you will achieve the goal. What preparations should you make to ensure you complete the project within budget?

Here follows the best advice on the documentation projects, before, during and after.

There are many types of technical and process documentation. If the project is compliance based (PCI, GDPR) concentrate resources on the documentation. Consider hiring a Technical Writer quickly for advice.

Capture the data/content

  • Check the availability of the Subject Matter Experts as well as other team members critical to the project
  • Consider the audience for the documents as that will determine the level and detail of the material.
  • Remember the level of content and information is only as useful as its source and the ability of non-technical audiences to use and follow the instructions/processes

Organise the document and content

Create a standard template with Heading and instructions regarding the level and type of material the TWs need to gather. As a guide use the following headings:

  • Work History
  • Versioning control
  • Scope/Out of Scope
  • Document Purpose
  • Document ObjectiveIntegrate Level 1 to 3 Headings to outline the topics.
    • You can base these decisions according to prerequisite documentation knowledge to provide the master plan for all future written work.
  • Does it require VISIOs/Screenshots?
  • Appendixes

Do NOT waste time creating project timelines to write and produce the documentation.

Until the information and gathering phase begins, do not even consider a guess about how long it will take to complete the documentation.

As the list of titles grows, Management may need to consider extending the budget to finance the project. Abandoning the documentation when it is ‘Nearly there’ will be waste of money, time and resources.

Decide the output format

When the Technical Writer has written the documents, consider which of the following formats will suit the company’s requirements.

  • MS Word stored in a Document Management System
  • PDF stored in a Document Management System
  • *.CHM files created by using such application as RoboHelp
  • Wiki formats: A Wiki provides the user community with the opportunity to provide documentation feedback

Future Review Requirements

Do not overlook the future requirements of any project. All documentation is an ongoing project. Establish a workflow between the IT teams/Process teams and the documentation department to update documentation.

  • Update the documentation when:
  • the IT teams upgrade or modify the Server/Application/technology
  • document all changes, using a change management process to prevent any repeat the configuration
  • align the documentation and the project

Revise the Project

On completion of the project Use the documentation to:

  • reflect the changes and updates
  • test to ensure instructions are clear, concise and correct
  • Avoid considerable time, frustration, and future expense by correctly applying documentation strategies to:
  •  . . . ensure that users can follow the instructions
  • . . . provide a historical record of the changes made during the project
Manage documentation projects before, during and afterClick To Tweet
Featured

Technical Writing | The cost of Technical and Process documentation

Why is it that companies view the cost of Technical and Process documentation as an unnecessary expenditure rather than viewing documentation as a centre of knowledge? Management seems to have a blind spot with documentation and conveniently forgets the role of documentation.

When redundancies beckon, I know how quickly management will sacrifice the technical documentation department. When management seeks layoffs, the technical author(s) will be amongst the first out the door. Months later a member of staff points out that the documentation is out of date and follows up by asking: do we have anything up to date we can use?

In sacking the technical documentation team, no one assumed responsibility. Keeping it up to date is left to those least inclined to keep it up to date. They are the people who would benefit most from its upkeep.

The cost of Technical and Process documentation
The cost of Technical and Process documentation

Within a software environment, we easily forget that as the developers progress their software application, it also becomes more complex. Failing to supply up-to-date documentation means customers can overlook many of the improvements and advanced features. We could say the same of any IT department. As the network grows, there are more questions and fewer answers. No one has a good overall knowledge of the network because of the lack of documentation.

Where does that leave technical writers?

However, you refer to us, be it technical authors, communicators, documentation staff or as the font of all knowledge. Never doubt our experience, our people skills, our ability to write clear instructions.  We can explain complex technical terms in easy-to-read formats. Who else will put up with blank stares, sarcastic comments and listen to comments such as “whaddya want now?’ to get what your company needs; usable documentation.

The cost of Technical and Process documentation
The cost of Technical and Process documentation

Remember, it is not about the cost of hiring a technical author. It is about our value to your organisation. Our documentation will keep your staff informed and up to date. There is a point to keeping your processes up to date as your working environment changes. It is also about keeping that software guide up to date enabling your customers to use your product more efficiently and know they invested in a superb product.

Finally, don’t forget that a technical author will not only you save money now but also at a later date and will keep on saving you money, therefore, over the long term justifying their value to your business.

The cost of Technical and Process documentationClick To Tweet

Featured

Technical Writing | Hiring a Technical Writer

Budgets for the job

When you start the process of Hiring a Technical Writer, my advice is thisdo not cut corners when sourcing a budget:

  • Check the daily rates/hourly rates. Do not expect an experienced technical writer if the daily rate is derisory.
  • If your rate is low, you will attract Technical Writers with less experience whereby the result could be a disjointed document with no formatting and poor English
  • A good TW who charges a higher rate may save you money by taking less time to do the job.

Your Technical Writer in the flesh

hiring a technical writer
Hiring a technical writer for your project

Many TWs will have worked in a variety of environments. In due course, we gain knowledge that could provide a solution to other long-running problems. Hence why managers should never underestimate TWs.

What will you need?

Before you actively engage the TW on your site, do you have all equipment ready:

  • One of the most common problems is no laptop on the day they start
  • That their profiles to log in to the network are set up
  • If they are reviewing existing documentation make sure it is available

When you start explaining the work to a TW in company-specific jargon, do not assume they understand you. There is a good chance that the TW during an interview may mention that what one company knows as “XYZ” may not be the same as yours.

What should you do?

  • Be certain the SMEs or others with whom the TW will engage are aware of the appointment and know the goals of the project
  • If you are the primary contact do not disappear without the TW knowing where you are or who is second in command
  • Do not assume the TW is less than proactive if you cannot see them writing down a list of questions and talking to the appropriate people. If they are reviewing existing documentation, they may need a few days to understand the content before they start acting pro-actively
Techwriting Hiring a Technical Writer
Hiring a Technical Writer

If after settling on a start date

If a problem arises let the TW know in advance because:

  • You may need to change the start date or find another job for the TW to assess.
  • Delays will only diminish your budget if the TW is on-site with nothing to do.
  • If the problems are likely to be ongoing be honest and let the TW know – do not consistently change the start dates because it is not very professional and TWs do talk to fellow TWs.
  • Be consistent with the project, its objectives, and deadlines
  • Do not change the parameters of the project by allowing project scope creep.
  • Communicate with the TW as S/he may not have the time to stay beyond the current time allotted for the project.
  • Make contingencies if you need to extend the contract

What will the Technical Writer do for you?

Supply a project plan. Do not expect one within a matter days. if they own a generic copy, they can adapt it for the project; else create one from scratch.

The project plan should include a documentation schedule, including milestones and how progress can be measured.

On longer projects, TWs will complete a weekly project management report, which will outline problems, issues, bottlenecks, etc.

If the contract states that travel abroad or within the UK is necessary, make sure they are available to go.

Foreign travel as part of the contract

Some companies expect contractors to pay their expenses up front on foreign trips.

Might I suggest that they:

  • Can afford to do so without getting into debt.
  • Know the procedure to claim their expenses
  • Be clear on when the payment will be paid
    • I once submitted expenses, which, due to a misunderstanding took three months to process.
Featured

Technical writing | Now that you have Technical Documentation

So, after the initial shock of discovering what happens when you have no technical documentation, what can you achieve now that you have technical documentation?

1: Have you employed/contracted a Technical Author . . . Great!! If not what’s holding you back . . . remember we bring value

2: If you cannot see your technical author at their desk you’ll no doubt find him/her performing Vulcan mind melds and extracting the necessary technical information from the heads of your development/infrastructure staff (if it looks painful don’t worry, the job is mandatory!)

3:  Start a discussion about what you need and I’m certain your technical author will only be too happy to help?

4: Once you have technical documentation there is no more guesswork as you have plenty of reliable data against which to measure the progress of future projects

5: You can also employ a project manager who can plan ahead because you know everyone who needs it!

6: Documentation is no longer a problem and what you require is what you will get . . . Congratulations!

Featured

Technical Writing | The Problem with Shared Drives

It is not unusual to find companies still use Shared Drives to store their documentation. As many Technical Writers will point out, the problem with shared drives is that they are neither secure nor searchable.

What is the problem with shared drives?

  • The folder structure has too many levels meaning documents are difficult to find
  • There are information gaps as users keep copies of documentation locally and not on the shared drive
  • There is no formal ownership of the documents
  • The title and subject of the document does not accurately reflect the content
  • Document versioning is not used meaning the latest version is  . . .  Where?
  • There are many copies of the same document
  • The failure to maintain a workable Archiving policy means many documents with the same title contain unchecked updates
  • There is no historical tracking of documents to keep integrity of the content
  • Searching for documents on a shared drive will raise many unrelated results

Using a non configured Document Management System (DMS)

It would seem ironic that companies do spend a large amount of budget on installing a DMS such as SharePoint but fail to task an experienced employee to set it up correctly. So what happens when the DMS is left to grow without the correct administration?

  • Failure to lock down user privileges means it becomes a free for all  with no proper administration
  • Check In, Check Out, Document Versioning and Security are not configured meaning user’s drop off documents where they see fit
  • There is no historical tracking of documents to keep integrity
  • Users create folders without proper titles and lose their document
  • Backup of the DMS is irregular

If you want to manage your documentation in a way in which it cannot become a free for all you need to consider a form of document control and establish a policy and a set of rules to keep your documentation in check.

Technical and Process Documentation is an asset, and your staff should treat it as such. Look after it, and it will look after your business.

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

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]

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