Category: Process Documentation

The difference between Policies, Standards, Procedures and Strategies

As a Technical Writer, I have written many policies, processes, strategies, standards and related documents. These documents outline how a business operates and provide help when a team member requires a reference.

I worked on a project where the PM insisted a document contained a process. When I said it was a strategy, he threw a hissy fit. He insisted and had no intention of listening. He is not the first who thought they knew better. 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 planned or adopted to reach its long-term goals. Management signed policies and published them in the Company’s preferred medium.

    • Writing Policies is to influence and determine major decisions.
    • Processes and procedures are the specific methods used to express policies in action in daily operations.

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 perform the process end-2-end.

      • A Process is a high-level description of a series of inter-related tasks covering an entire business.
      • It is an internal, ongoing process updated annually, as policy guidelines serve 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 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 how to do a specific task step by step.

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 how to allocate resources and provides backup plans if resources are not available at a crucial time.
      • The Plan document outlines the components to show 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 how an organisation will move from point A to Point B.

      • How will you get there?
      • Issues, problems
      • Solutions and tools to get you to point B

A strategy solves the move from A to B, considering 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 sound strategic planning decisions that separate the two.

What is the standard?

Standards are mandatory actions or rules that give formal policies support and direction. Writing standards requires a company-wide consensus on what standards must be in place. It can be a time-consuming process vital to the success of your information security program.

      • They are written to show 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!)

Content and Documents | How Can I help you?

In the aftermath of Coronavirus, many managers may know they have documentation projects in the pipeline and, on their mind, is hiring a technical author. As a contract Technical Author with 20 years plus experience, what can I offer you?

What type of documentation will your project need?

With 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 more ease?

I have a vast collection of generic documentation covering PCI, ISO27001, GDPR, ITIL. 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 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 the information 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. 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: twriter201@gmail.com

Technical Writing | General Data Protection Regulations

GDPR

On the 25th May 2018, the new General Data Protection Regulations (GDPR) came into force.

Companies outside the EU

If your Company actively trades within the EU and stores, processes or shares EU citizens’ data, then GDPR does apply to you.

Compliance and documentation

One of the primary rules is that under GDPR Process activities MUST be documented.

Companies are required to maintain a set of Policy, Process and Plan (PPP) documentation to ensure you have evidence to support your claims should the ICO investigate any complaint or breach of data.

Note that the Information Commissioners Office (ICO) could demand to see the written documents

What do you need to consider?

As a technical writer, with experience writing compliance documentation, what can I tell you?

If you are still struggling to start

My Blogs are clear, writing one document, when there is a substantial list to be completed from scratch to sign off is a lengthy process. Even if your department has documents that can be reused, it will still take a long time. Compliance projects are manually intensive and documenting GDPR will need dedicated resources.

My experience could be necessary to help you write and manage those documents. The sooner you contact me, the sooner we can start the road to compliance.

  • Create a standard template with – Statement, In Scope, Version Control, Change History, Distribution Lists, Roles and Responsibilities
  • All PPPs must adhere to GDPR – include in the document ‘The purpose of the document’, ‘The Scope’ and add a list of the GDPR compliances relevant to the PPP you are writing and explain the WHY the company are complying along with the HOW the company will comply.
  • The documentation must be relevant to your business. Generic documentation outlining a PPP will NOT suffice
  • Complete the documentation – do not start and leave a document incomplete then sign off; an incomplete document could fail a Compliance Audit
  • Maintain the detail – do not half explain a process or policy
  • Structure the documentation to avoid duplicating information over several documents
  • That the documentation may need to be ISO 27001 compliant

Does Your GDPR Project need documentationClick To Tweet

 

Technical Writing | 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 | Hire a Technical Writer sooner, rather than later

As a Technical Writer with over Twenty Years of experience, I need to address a problem which haunts documentation projects. I aim this at Project Managers who scope such projects as part of a more comprehensive project.

Have you ever planned a project (PCI, GDPR, ISO27001, ITIL, Policy and Process) where documentation is critical? If so, how did it go? Crucially, did the project deliver ALL the documentation? If not – do you know why the plan failed?

First: Did you speak to a Technical Writer for a realistic appraisal of the expected outcomes?

Second: was your budget a few pennies short?

A collective failure of technical / process documentation projects is the lack of knowledge and expertise during the planning and discovery phases. Many project managers do NOT grasp the reality of a documentation project.

If the PM does NOT know the difference between a written process, a documented plan, and the purpose of a policy and its processes, your project could be in trouble.

The planners do not understand the lifecycle of a document, from the initial draft through various reviews and sign-off. The process takes much longer than expected.

How long does it to write a document? My default answer is “I do not know”. Technical Policy and Process documentation, depending on the project (PCI, GDPR, Operations, ITIL), will have many requirements and factors which delay the following stages:

      • the information gathering,
      • the interviewing
      • opinions
      • the writing,
      • review stages,
      • amendments
      • opinions, and
      • sign-off.

The likely reality of writing a 30-page A4 process 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)

It will take at least 8 – 12 weeks of effort before the review stage. My advice is not to plan such a project without professional help.

Compliance projects such as PCI and GDPR generate a lot of policy and process documentation. If you are starting from scratch, the list of required documents could exceed 60 or more. In timing terms, you are looking at 12/18 months of work. To be safe, let’s say 24 months. If you have partially written documents, DO NOT expect timings to diminish to a few months. If the papers are scattered throughout various drives, the technical author must first attempt to get the documentation into a consistent state. That could take months of work.

Finally, there must be a management agreement to help the PM and TA find the resources to succeed. Any failures will multiply costs.

Hire a Technical Writer

My advice is this: If you have a project that requires documentation, hire a Technical Writer, not a Business Analyst, for advice from the start of the project, NOT when the end date is in sight and when the budget is running out. The TW can highlight issues, risks, and bottlenecks and help you manage expectations within the allocated time assigned to the project.

The Technical writers will need:

    • 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, and resignations from the project. They happen.

If the budget and the timelines become fixed (in stone) with multiple documents to complete in a short period, then produce quality rather than quantity.

To ensure quality, rank the documents across the 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 affects nothing else on the project
    • W – I would like to have this requirement later, but delivery won’t be this time.

Additional Points

    • Travel: Will the TWs need to travel abroad or nationally?
    • 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 size 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.

In contrast, documentation projects succeed due to:

    • excellent planning
    • understanding of documentation lifecycles
    • allowing enough time to complete the documentation.

Finally: If the project’s success 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?

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?

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.

Techwriting | Technical and Process Documents

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.

Tweet
Share5
Share

The cost of Technical and Process documentationClick To Tweet

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.

%d bloggers like this: