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 | Project Managers and Technical Writers

Can project managers and technical writers get along?

I always make the point to Project Managers that Technical Writers are highly organised. They juggle numerous tasks and switch between them with ease. They also have great people skills working with coders, engineers, and technicians of various shades. In the meantime, they manage a ream of documentation while taking instructions from SMEs. Occasionally a project manager who has never had to consider technical documentation as part of a project offers advice.

techwriting
Project Managers and Technical Writers

 

The technical documentation component of a project does require 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 the project (because it’s documented), and better internal and external support through documentation.

If you are one of the many Project Managers who has never worked with Technical Writers, bear in mind that 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 the following:

  • Take time to 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.
  • TWs 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).
  • Time required for writing
  • Peer reviews
  • Time to have the content technically reviewed

Technical Writing | Passive vs Active Sentences

What is a passive sentence?

A Passive sentence is a grammatical voice prevalent in many of the world’s languages. In a clause with passive voice, the grammatical subject expresses the theme or patient of the main verb – that is, the person or thing that undergoes the action or has its state changed.

http://en.wikipedia.org/wiki/Passive_sentence

Passive vs Active

I can already hear readers asking, what is a Passive Sentence?

Here goes!

Compare these sentences.

  1. The Application is used to collect data (passive)
  2. Use the application to collect data (active)

or

  1. The key was used to open the door (passive)
  2. Use the key to open the door (active)

or

  1. The wire is fed through the box by the electrician (Passive)
  2. The electrician feeds the wire through the box (active)

In my opinion, using the active voice, sentences provide a clearer more effective message in technical writing and business writing. The active voice clearly identifies the action and determines who performs that work. For clear examples of passive voice take a look at government documents, which gives the wording a dull, bureaucratic tone.

Over time, writing in the passive voice becomes a habit, one we should all work to change. Of one thing I can be certain, despite the debates, I will continue to use the active sentence.

Technical Writing | Interviewing SMEs

Without Subject Matter Experts to impart their knowledge about their technologies writing that content will be a harder job. So, how does an experienced technical writer consider approaching and interviewing Subject matter experts?

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  Subject Matter Experts 

  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 be working 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 is relevant 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 object, it will mean listening intently and writing down the information
  6. Approach the Interview at the appointed time:
    • Do not be surprised to find the SME cancels the meeting due to 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 make it clear 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 introduce the project and you if you have not already done so introduce yourself

  12. The SME may not know everything and may need to refer you to another SME for information
  13. When you return to your desk, start writing up the document. Do not wait for a few days, even if you have recorded the interview
  14. Carry a pad and pen. You may need to ask the SME to draw the infrastructure

Technical Writing | Professional vs Amateur, its a matter of choice

A LinkedIn connection shared a poster, which read: Professional vs Amateur; If you think it’s expensive to hire a professional, wait until you hire an amateur.

In 2004 I had two interviews; one in Watford and Cambridge. Both were software companies looking for a Technical Writer. Neither interview went to plan as in both cases the interviewer seemed distracted and uncertain what to ask.

When the respective agents called with the feedback, both companies followed a similar route. To keep costs down they appointed an internal resource.

Later that year I received a telephone call to tell me that the Watford company after a management buy-out sacked the TA. His documentation failed to meet standards. I was later told that the Cambridge company began to search for an experienced Technical Author after the internal appointment failed to deliver.

The third situation arose when a previous client called. One of their technical writers had left with work to complete. Once I analysed the work, I made it clear that 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 technical writers will point out that you get what you pay for. Be ready to pay the going rate to attract an experienced technical writer who is more than capable of doing the job. You also need to consider our role is not as straightforward people think. There is more to the job than an amateur might think.

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.

Technical Writing | Sourcing a technical writer

When sourcing a technical writer, you will need to ensure that their experience matches your requirements. It goes without saying that you need to source one who has the right knowledge, background and expertise. At the interview they should aptly demonstrate that experience by way of samples; 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 be building 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 employing a Technical Writer on a permanent basis unless you are sure there will be ongoing work.

Work cycles can and do 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. In my opinion, this is why the position of Technical Writing lends itself more so to contract work rather than permanent work.

To summarise: if you employ a permanent Technical Writer ensure you have plenty of contingencies within the scope of 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 be covering will not go down too well.

A word of caution

Unfortunately, our profession can and does 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 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, when it comes to 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 employing 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.

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.

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.

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