Featured

From Contract to Permanent

my transition from contractor to perm

In 2004, while staring at redundancy for the third time, I accepted a six-month contract with BT to fill a potential gap until a permanent role emerged. A former colleague told me that contracting can be a long-term career choice. However, transitioning from a contract to a permanent position can be challenging. He offered various reasons, but I went ahead; I couldn’t afford to be out of work.

trnsition from contract to perm

My first two contracts were with BT in London and their HQ in Ipswich. Then came T-Mobile (now EE), NTTE, and Capita. Before I knew it, five years had gone by, and recruitment agents were calling with contract and permanent jobs. 

However, some agents were reluctant to forward a contractor to a client wanting a permanent technical author. Recruitment agents had stories of contractors accepting a permanent role and quitting after a month (or a week) to return to the contract market. Yet, while I interviewed for several permanent positions, none matched what I wanted.

So, every year, I hopped from one contact to another on multiple tasks, occasionally meeting TAs with stories on workplace experiences; we all understood each other and provided a laugh. 

Note: To be a technical author, you need a sense of humour and a sharp wit.

However, I never got to grips with the gaps between contracts. While the money was above average, allowing me to pay myself an inconsistent amount every month. During the 2008 financial crisis, my earnings dropped by a massive 33%, not helped by a four-month contract gap. During that period, Blackberry offered me a permanent role. Unfortunately, I didn’t stay long because of an overzealous  Canadian-based micro-management team leader. So desperate to make her mark, she called me when she arrived at her office in Waterloo, Ontario. She said during one call I must learn to manage my stress. Yet, she caused me stress by constantly interfering and telling me how to do my job—her two years of experience against my 13 years.

Yet, look on the bright side: with more contracts under my belt, I developed more skills: 

  • SharePoint (Document Management)
  • Confluence
  • Help Desk support, transition from contractor to perm
  • policy & process writing, 
  • VISIO process flows
  • ITIL (incident and change management), 
  • ITSM. 
  • PCI/DSS, 
  • ISO 27001 Audits and 
  • operations manuals for data centre migrations and
  • project management

Goodbye to software environments and hello to the broader world of technical authoring. Not only did I widen my experience, but I also travelled to Pune in India, Germany, Belgium, and Canada. 

I have started but cannot finish.

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

A common trend with contracts is poor budget allocation. In one PCI/DSS project, I worked with two technical authors on a 10-week assignment. When we arrived, the PM had used most of the budget to prepare for an audit, which involved hiring an expensive external consultant with high fees.

We needed to prepare the groundwork, identify SMEs, and divide the sixty titles between us. After five weeks, we began talking to SMEs and writing the documents. But the task was beyond our efforts—too much to do and insufficient time. While the company in question went bust during the pandemic, it had nothing to do with the project. 

Hiring managers and project managers often struggle with the dynamics of documentation projects. Many project managers assume documentation to be a straightforward task. It rarely works out that way.

On my journey to a permanent role, the points below formed the basis of my decision. If you are a contractor considering a change towards a permanent position, consider what you could offer as a permanent employee.

  • I could concentrate on doing what I’m good at rather than spending gaps and seeking new freelance jobs.
  • Working as a freelancer has allowed me to improve my flexibility and adapt to new situations. Technical authors MUST know the meaning of flexibility and the ability to work alone or in a team. 
  • I respond to many people, environments, and attitudes. This experience makes it easy for me to work well with different management styles and personalities.
  • Can they manage me? Even as a freelancer, my remit is contributing to a team. And as a freelancer, I have always been “managed…” by my clients.
  • How would you benefit our clients? If you want me to get involved with client contact, I can help with their needs with knowledge and experience and offer documentation solutions. 

We are also

    • I am confident our considerable Skillset will shine through.
    • Understand issues and be ready to hit them head-on. 
    • experience of multiple environments
    • recognition of common problems
    • Understanding of project needs
    • broad experience
    • Renewed enjoyment of teamwork

What are you thinking? 

Maybe you are thinking, how can I shift from contract to perm and take a sharp hit in my pocket? As a contractor, my earnings fluctuated, with no consistent monthly payments due to:

  • The time between contracts (a few weeks to a couple of months). 
  • Increasing administration and overheads through my limited company. 
    • unemployment insurance (£150 per month to cover me in case of an injury or debilitating illness),
    • personal and public liability insurance (£10m in value £160 p/a), 
    • private medical for quick treatment (£1200 p/a)
    • accounting fees (£1200+ p/a)
    • Travel costs were deductible; 
      • Car mileage
      • Air Fares between Brussels and Gatwick
      • Hotels and meals while working away from home in the UK
    • Increased Taxation on Dividends
    • The Government fails to grasp that we risk takers don’t have holiday pay, sickness benefits, or company benefits.

Pre-pandemic, I received about five calls a week from agents checking my availability for work. Meanwhile, I maintained a growing Excel spreadsheet of calls listing potential clients and reinvented my CV every six months.

During the pandemic in 2020, I was out of work from March to October. My company accounts for 2020 saw a £5000 loss and a £3000 loss in 2021.

In April 2021, to circumvent IR35, I joined an umbrella organisation.

Post-pandemic, IR35 played havoc with the contract market and caused an enormous drop in calls from recruitment agents. 

Here's a fun fact. In eighteen years as a contractor, I worked at 45 different companies. That doesn't include about ten companies where I walked away after a few days to avoid a disaster in the making.

Why did I walk?

The hiring manager sold me a dud while management expectations were unrealistic..

Between 2004 to 2021 over 300 hiring managers received my CV and more than half interviewed me.

The last journey

In 2021/22, after I completed a long-term contract project, I focused on finding a permanent role. Most calls were for permanent work. The HR department of a County Durham-based bank (my home county) offered me an interview. However, HR rejected me because of my contracting background. So, if you are reading this, take note. I am now a permie, see what you missed. 

transition from contracting to perm

While I had three more interviews, the sticking point was the salary. A business owner, one lady, called after finding my CV online and offered me a perm role paying £35K after a five-minute discussion.

And Finally…

So, when I read the Atkins job description, I thought, let’s give it a go, with nothing to lose. During the interview, the interviewer asked the inevitable question. I refer the reader to the first three paragraphs of this post. 

After quitting the contract market, I am no worse off when considering my salary and the benefits I receive. I no longer worry about tax bills, dividend taxes, accounting fees, and various insurances costing a fortune. A permanent role has worked for me and might work for you. Never say never.

Featured

Technical Authors what we are and what we are not

Unveiling the True Potential of Technical Authors: More Than Just Writers

Don’t let the title of Technical Author fool you. Regardless of your opinion, do not underestimate us. We have the potential to offer unexpected help in more ways than one. Allow me to dispel the myth regarding our identity.

Misconceptions About Technical Authors

Not Just Software Developers

If I had proficiency in BASIC, C/C++, Java, etc., I would earn significantly more as a developer. While I receive calls for API documentation, a skill requiring familiarity with code, my primary focus remains on creating clear and concise technical documents.

Not Project Managers

I am not a project manager certified through Prince2, Agile Scrum, or similar programs. My project management skills are specific to technical documentation, where I manage schedules and meetings with subject matter experts (SMEs) and other stakeholders. My role does not include:

  • Detailed project planning, progress evaluation, risk management, or issue resolution. For these tasks, a full-time project manager is essential.
  • Secretarial duties such as organising colleagues’ schedules or taking minutes. I record my meetings and extract the relevant information for documentation purposes.

Not Departmental Experts

While familiar with the terminology, I am not an expert in every department. I learn on the job, facilitating communication and collaboration through practical verbal and written skills. My goal is to support and encourage achieving organisational goals without making the process daunting.

The True Role of a Technical Author

An External Consultant with a Plan

As an external consultant, I often use the MoSCoW method to categorise initiatives into must-haves, should-haves, could-haves, and will-not-haves (or wishful thinking). This approach ensures a structured and prioritised documentation process.

Documentation Management

Upon joining, I sift through all available documentation to identify gaps and areas for improvement. I manage documents and content using tools like SharePoint and Confluence, ensuring efficient information management for your teams.

Project Management Skills in Context

My project management skills, while not as extensive as those of a certified project manager, include:

  • Designing new templates and improving the structure of existing documents.
  • Documenting processes across several categories and arranging meetings with SMEs.
  • Planning, writing, reviewing, publishing, and maintaining content using tried and tested methods.

Extensive Experience and Resourcefulness

With over 23 years of experience, I possess an extensive library of generic documentation and various templates. This resourcefulness lets me tweak documents to meet your business profile, saving time and money.

ITIL and ITSM Expertise

I have experience producing IT Service Management (ITSM) documents based on ITIL best practices, including:

  • Service Design, Service Transition, Service Operation, and Continual Service Improvement.
  • Delivery and Service Support, Availability, Capacity, and IT Service Continuity Management.
  • Incident, Problem, Change, Release, Configuration Management, and Service Desk documentation.
  • Policy, Process & Standards documentation for ISO27001/9001 compliance, GDPR, PCI/DSS, and security projects.
  • Disaster recovery scenario documentation.
  • Infrastructure documentation to support large-scale networks and recently migrated infrastructures.

Editing and Enhancing Existing Content

I can enhance existing content by adding VISIO drawings, new screenshots, rewording policies, adding narratives, and creating new templates. I am also skilled at ensuring consistency and structure in Word documents.

Tools and Techniques

I keep projects on track using spreadsheets, MS Word, PowerPoint, and VISIO. I also suggest ways to maintain up-to-date and current documentation, treating information as an invaluable asset.

SharePoint and Confluence Management

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

If you lack a documentation strategy, I can create a plan tailored to your needs. Proper management includes ensuring documentation is available to all staff, appropriately updated, rewritten, and archived. Ownership, version control, and historical control are critical aspects of effective

documentation management.

Key Benefits of Effective Technical Documentation

Implementing adequate technical documentation can lead to the following:

  • Reduced costs.
  • A more responsive help desk/support system.
  • Better-informed staff and confidence in performing procedures.

By recognising the true potential of Technical Authors, organisations can leverage their skills to achieve greater efficiency, clarity, and overall

success.

Featured

Get a head start

Templates with generic content

Do you have a documentation project lurking in the background and you are yet to get to grips with the detail? I have available many templates which contain generic policies, processes, and standards content relating to the following documentation:

      • PCI/DSS
      • ISO27001
      • ITIL
      • ITSM

If you are embarking on a project for any of the above from scratch, you can save time measuring into months by using the relevant template.

Consider the fact it can take upwards of six weeks to produce one document of between 20 to 30 pages, imagine the scale of the work if you have more than sixty titles to write from scratch.

The content within the documents will require tweaking to make them relevant to your company, such as Team names and Team members, Technical terms and branding.

However, be aware I do not own a comprehensive list of Policy and Process documents. My library covers the documents that will take time to produce.

VISIOs

I own VISIO drawings covering the following and many more:

      • Incident management
      • Change management
      • Problem management
      • Document lifecycle

Templates with Headings only

You may require a set of pre-headed templates to help you document your Network. You can use these templates to document your servers and use the documents for many purposes.

Training: help new starters gain knowledge about the Network.

Audit: Have to hand information that can help you manage your Network over the long term.

Data Centres: Use the templates to plan a data centre migration.

      • Operating documents
      • Installation guides
      • Profile documents (5-Pages)
Featured

Technical Writing: The Survivior’s Guide

Have you ever thought about the role of a technical writer? This booklet based on my Blogs will give you the highs and the lows of the job.  You might learn something useful.

To buy a copy click on the link below.

Featured

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.

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

Give us a break

Give us a break. We need it. I write with authority and experience with over 25 years of experience as a technical author. My enthusiasm for delivering clearly defined documentation/content strategy has never diminished. Yet, two common issues remain for which I have no answer:

      • management expects a quick return on their budget, and
      • meeting people who think our role is a waste of time.

Our role is vital, and without us, standards of written and oral communications will forever diminish. Like many technical writers, I have various skills which overlap into different roles. I may operate under the title, technical author, but I have many more job titles under my belt. What skills do you ask? I communicate with many experts and produce relevant policy and operational process documents regarding maintaining a network. While I may not have the technical knowledge, I could step into a role and manage the infrastructure by working with technical teams. 

What can I tell you?

  • 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,
        • analyse workflows and write complex processes with drawings to help teams work more efficiently.
  • our job is never 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 expect to see results within a short period based on an issue that has continued unchecked for many years, you will be disappointed.

Many assume we do a cut-and-paste job and do not know that writing and managing reams of content is a fundamental role. If not, companies would not need people like me to make sense of the problem, offer a solution, and complete the job.

What do we do?

I have worked with developers, engineers (of varying shades), and experts in IT subject matter. The majority either:

        • Regard documentation as a luxury,
        • write their documentation, or
        • I do not 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 responsibilities. 

What do we offer? 

We link the business and the users by describing the product’s potential. Knowledge management: if the knowledge resides in a team member’s head, 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.
        • They can create newsletters—internal and external.

Who cares? No one reads it! 

Try telling that to your customers who spend more time calling your helpdesk. If your documentation is not updated and compatible with their version, you will hear loud and clear complaints. 

Businesses forget their T&Cs contain a clause that explicitly clarifies providing documentation. 

Relax at work! 

We get little time to relax because we’re always looking at ways to improve the documentation quality. 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.

This profession has a high level of stress due to a lack of communication. 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. 

If that is the case, 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 before deadlines to make the required modifications.

People assume technical writers only write and think it’s a straightforward job. The importance of technical writing will come when they understand:

      • The actual work we do, as technical writers,
      • 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:

      • SMEs have their responsibilities, and documents are way down their list
      • gaps in the content are common because they don’t believe certain functions are worth mentioning.
    • A technical writer will revisit the documentation, test for cracks, and add 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

One of the many skills a technical writer needs is the ability to form relationships with SMEs. An experienced writer talks to subject matter experts to gather insights for a document. Without their input, the writer will face difficulties producing documents. On one project, I worked with two technical writers. They had their styles of approach, and I have mine.

One of our team members, x,x, had a style and approach that rubbed many SMEs the wrong way. I have a laid-back approach. If the SME could not talk because of urgent work, then that’s fine—we can reschedule the conversation. X.X found it difficult to communicate with technical SMEs, which made it challenging to gather the information. He had never worked in the technical field coming not from a technical background, but a process background where people are polite.

Approaching and Interviewing  SMEs 

  1. Ensure you schedule a meeting with the SME in advance. Please do not turn up at their desk and expect to talk.
  2. If you collaborate with other technical writers, review the project plans and inquire whether they have contacted the subject matter expert (SME) regarding topic XYZ. If they have, verify the information is what you need. In such cases, refrain from requesting the SME to reiterate the information.
  3. I use a dictaphone to record interviews because I can always run the recording back if I have any queries. 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
  4. 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
  5. Always regard the interview as another knowledge-capture exercise that adds to your experience. Do not assume you know everything before you get there, even if you do.
  6. The SME will assume you understand their language; if not, stop the interview and request a less technical explanation or reassess your ability to do the job if you still do not understand.
  7. Schedule only an hour for the interview, but be clear that you will need to reschedule more time if specific points are unclear.
  8. Be transparent – there will be a peer review required, but you will let them know in advance when the document is ready for review
  9. 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 if you have not already done so, introduce yourself

  10. The SME may not know everything and will refer you to another SME for information
  11. When you return to your desk, start writing the document. Do not wait for a few days, even if you have recorded the interview.
  12. 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 writer, ensure their experience matches your requirements. The best candidate will have the correct background and expertise. Listen carefully to their answers as many like me at the interview dispense advice and why a particular route may not work. If they don’t talk through that experience, 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 career in various businesses, the broader and more in-depth their experience will be. However, the only way to be confident is to read their CVs carefully.

Read the CV, and discuss the project. My rule is this: if you cannot see it on my CV, then I haven’t done it. That does not mean I will turn down unfamiliar tasks.

Do they use Social Media or have a website?

Check out LinkedIn for their profile; If you cannot find it 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 offer suggestions on elevating the project with innovations you may not have considered.

Effective communication

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

Do you want a contractor or permanent TW?

Do you want to build a team that includes a TW to keep the documentation up to date, a person who will grow into the environment? However, I caution against hiring a permanent Technical Writer 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 as 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 an odd spurt of activity within the working life cycle; hence, the position of Technical Writing lends itself more to contract work than permanent work.

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

A word of caution

Unfortunately, our profession attracts its fair share of triers. You can reasonably expect CVs from candidates who have had minimum experience preparing ad hoc documentation on projects at work. Unfortunately, that minimal experience does not translate to full-scale projects requiring a technical writer. In many cases, it turns into an expensive flop.

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.

To avoid problems, apply the following advice:

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 limits the Technical Writer’s experience. That also goes for junior writers. For high-profile projects, hire a seasoned contracting professional who can talk through the project with you.

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

Where else can you source a Technical writer?

You have found me. However, I may not be suitable for the role. Check LinkedIn, Social Media sites and 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 that, 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 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?

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

IT Managers often undervalue the importance of technical documentation until they realise its absence. Listed below are six reasons why your business needs technical documentation.

      1. If you don’t have technical documentation, there won’t be any records of past projects in 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. The team is guessing their way through the upgrade project. . . 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 essential; 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.

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.

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.

the process for applying patches to network servers

Scheduling: To minimise disruption, choose a low usage period when the Network is not in use.

IT professionals must follow processes before and after installing server patches or fixes to ensure system stability, security, and compliance. Here’s a detailed overview of these processes:

Before Installing Patches/Fixes

Identify and Assess Patches:

    • Gather Information: get patch details from vendors or reliable sources, including release notes and potential affects.
    • Risk Assessment: Evaluate the risks associated with the patch. Determine if it addresses critical vulnerabilities or bugs and assess the potential impact on existing applications and services.

Plan and Schedule:

    • Patch Management Policy: Adhere to the organisation’s patch management policy, which includes guidelines on patch prioritisation, timing, and approvals.
    • Scheduling: To minimise disruption, choose an appropriate time for patch installation, preferably during maintenance windows or low-usage periods.

Backup:

    • Full Backup: Perform a full system backup, including data, applications, and configurations. Store backups securely and can be quickly restored if needed.

Testing:

    • Staging Environment: Apply the patch in a staging or test environment that mirrors the production environment. Do not load directly onto the production environment.
    • Testing: Conduct comprehensive testing to ensure the patch does not cause issues. This includes functionality tests, performance tests, and compatibility tests.

Communication:

    • Notify Stakeholders: Inform relevant stakeholders, including users and management, about the upcoming patching activities, potential downtime, and expected outcomes.

Rollback Plan:

    • Create Rollback Procedures: Develop a plan to revert to changes if the patch causes issues. Document and test the rollback procedures.
    • Change management: follow any change process with a rollback to avoid potential failure.

During Installation

Pre-Installation Checks:

    • System Health Check: Verify that the system meets all prerequisites for the patch.
    • Ensure Backup Completion: Confirm successful completion of the backup process.

Apply the Patch:

    • Follow Vendor Instructions: Carefully follow the installation instructions provided by the patch vendor.
    • Monitor the Process: Monitor the installation process for any errors or warnings.

After Installing Patches/Fixes

Verification:

    • Confirm Installation: Verify that the patch has been installed correctly and is active.
    • Functionality Testing: Re-test critical functionalities to ensure they are operating as expected.

Monitoring:

    • System Monitoring: Closely monitor the system for unusual behaviour, performance degradation, or errors.
    • Log Review: Check system logs for any anomalies or issues post-installation.

Documentation:

    • Update Documentation: Record the details of the patch installation, including date, time, system changes, and any issues encountered.
    • Change Management Records: Update change management systems with the patch details.

Communicate Completion:

    • Notify Stakeholders: Inform stakeholders that the patching process is complete and provide an update on the system status.

Post-Implementation Review:

    • Review Meeting: Conduct a post-implementation review to discuss what went well, any issues encountered, and lessons learned.
    • Refine Processes: Update patch management policies and procedures based on the review findings to improve future patching activities.

 

Discover the differences between technical authoring and content writing. Explore the skills and expertise required for each role in this insightful discussion.

Agent: I have a client looking for a content writer, and given your extensive experience as a technical author, you might be a great fit.

You: Could you send me the job description?

Agent: Absolutely. I’ll send it over now. [Sends job description]

You: Thanks. I’ve received it. Let me take a quick look. [Pause as you read] This job description requires a technical authoring role and not a content writer. They require expertise in documentation, software tools, and advanced writing skills.

Agent: I see what you mean. The client seemed a bit confused about their exact needs. They wanted someone to handle content and mix it with technical documentation abilities.

You: Right. They sound confused and don’t know our differences. Technical authors specialise in the tasks listed here. Creating user manuals and working with software development teams. Content writing typically involves creating marketing materials, blog posts, and web content, which is quite different.

Agent: That makes sense. The client might not fully understand the distinction. Given your background, do you think you could still be a fit for this role?

You: I have the skills and experience to handle the technical authoring aspects of the job. However, the client needs to understand what they truly need. If they’re looking for someone to handle technical documentation, then yes, I’d be a great fit. However, if their primary need is content marketing, they might seek a different skill set.

Agent: That’s a good point. I’ll go back to the client and clarify their needs. Would you be interested in proceeding if they confirm they need someone with your technical expertise?

You: Absolutely. If they need a technical author, I’d be interested. Just make sure they understand the distinction so their expectations align with the requirements of the job.

Agent: Got it. I’ll speak with them and get back to you soon. Thanks for your insights and for pointing out the discrepancies.

You: No problem. I’m happy to help. Looking forward to hearing from you.


Clear communication and understanding between the agent, the candidate, and the client are crucial in accurately matching the job requirements with the candidate’s skills and experience.

The Differences Among Writers: Roles, Responsibilities, and Skills

Companies need a better understanding of the roles, responsibilities, and skills needed for each writer. This knowledge enables them to identify the type of writer needed for tasks such as:

  • crafting captivating blog content,
  • producing technical documentation,
  • developing persuasive marketing copy,
  • designing user-friendly interfaces, or
  • creating winning bid proposals.

The Differences Among Writers: Roles, Responsibilities, and Skills Writers:

1. Content Writer

Responsibilities:

  • Writing articles, blog posts, and web content.
  • Researching to ensure accuracy and depth.
  • Optimising content for SEO.

Skills:

  • Strong writing and grammar skills.
  • Understanding of SEO principles.
  • Ability to write in various tones and styles.

2. Copywriter

Responsibilities:

  • Creating persuasive copy for advertisements, marketing materials, and product descriptions.
  • Developing slogans, taglines, and promotional content.
  • Collaborating with marketing and design teams.

Skills:

  • Excellent persuasive writing skills.
  • Creative thinking and idea generation.
  • Knowledge of marketing and advertising strategies.

3. Technical Writer

Responsibilities:

  • Writing manuals, user guides, and technical documentation.
  • Simplifying complex information for a non-technical audience.
  • Working with engineering and product teams to research information.

Skills:

  • Strong technical understanding and ability to learn new technologies.
  • Clear and concise writing style.
  • Attention to detail and organisational skills.

4. Grant Writer

Responsibilities:

  • Researching and identifying grant opportunities.
  • Writing proposals and applications to secure funding.
  • Communicating with funding organisations and stakeholders.

Skills:

  • Persuasive writing and storytelling.
  • Understanding of grant processes and requirements.
  • Intense research and organisational abilities.

5. Ghostwriter

Responsibilities:

  • Writing content on behalf of another person, often for books, articles, or speeches.
  • Mimicking the voice and style of the client.
  • Interviewing and research.

Skills:

  • Adaptability in writing style.
  • Discretion and ability to maintain confidentiality.
  • research and interviewing skills.

6. Scriptwriter (Screenwriter)

Responsibilities:

  • Writing scripts for films, TV shows, commercials, or video content.
  • Developing dialogues, characters, and plotlines.
  • Collaborating with directors and producers.

Skills:

  • Strong storytelling and dialogue writing.
  • Understanding of film and TV production processes.
  • Creativity and ability to develop compelling narratives.

7. Editor

Responsibilities:

  • Reviewing and revising content for clarity, grammar, and consistency.
  • Providing feedback and guidance to writers.
  • Ensuring content aligns with brand voice and guidelines.

Skills:

  • Excellent grammar and editing skills.
  • Attention to detail.
  • Strong understanding of writing styles and tones.

8. Journalist

Responsibilities:

  • Investigating and reporting news stories.
  • Interviewing and research.
  • Writing articles for newspapers, magazines, or online platforms.

Skills:

  • research and interviewing skills.
  • Ability to write under tight deadlines.
  • Objectivity and adherence to journalistic ethics.

9. Social Media Writer

Responsibilities:

  • Creating content for social media platforms.
  • Developing engaging posts, captions, and multimedia content.
  • Analysing social media metrics and adjusting strategies.

Skills:

  • Understanding of social media trends and platforms.
  • Creative and concise writing.
  • Ability to engage and interact with an audience.

10. Content Strategist

Responsibilities:

  • Developing content plans and strategies to meet business goals.
  • Coordinating with writers, designers, and marketers.
  • Analysing content performance and optimising strategies.

Skills:

  • Strategic thinking and planning.
  • Understanding of content marketing and SEO.
  • Strong project management skills.

11. UX Writer

Responsibilities:

  • Creating user-friendly copy for websites, apps, and other digital products.
  • Writing microcopy, such as buttons, error messages, and tooltips.
  • Collaborating with designers, product managers, and developers.

Skills:

  • Understanding of user experience (UX) principles.
  • Ability to write concise and clear copy.
  • Experience with user research and testing.

12. UX Strategist

Responsibilities:

  • Developing UX strategies to enhance user satisfaction.
  • Conducting user research and analysing data.
  • Working with cross-functional teams to implement UX improvements.

Skills:

  • Strong understanding of UX design and principles.
  • Analytical and research skills.
  • Ability to develop and communicate strategic plans.

13. Bid Writer

Responsibilities:

  • Writing proposals and bid documents for contracts and projects.
  • Ensuring compliance with bid requirements and guidelines.
  • Collaborating with sales, finance, and technical teams.

Skills:

  • Persuasive writing and attention to detail.
  • Understanding of bid processes and regulations.
  • Strong organisational and project management abilities.

10 Key Differences Between Content Writing and Technical Writing

10 Key Differences Between Content Writing and Technical Writing

Technical writing and content writing are often mistaken for the same, but they are two distinct fields. While both require strong communication skills, they serve different purposes and audiences. I will explore 10 key differences between content writing and technical writing in this article. The aim is to help aspiring technical authors understand the nuances of technical writing.

By understanding these differences and focusing on specific skills, aspiring technical authors can speed up their technical writing journey and become experts in just one week.

This article addresses the following queries:

  1. Purpose: When You Should Create a Content Copy and When Technical Documentation

Content writing: aims to entertain, inform, or persuade readers. It engages and keeps the audience’s interest through storytelling and emotion-based appeals.

Technical Writing: Technical writing focuses on conveying complex information to educate readers about a specific topic or to guide them in performing a task.

Tips for Aspiring Technical Writers: aspiring authors should prioritise clarity over creativity. Understand the purpose of your document and ensure that your writing serves that purpose.

2 Audience: Know Your Audience like the Back of Your Hand

Content Writing: Content writers often target a broad and diverse audience, aiming their content at anyone who finds it interesting or valuable.

Technical Writing: Technical writers write for a specific audience, often professionals in a particular field or users of a specific product. Their audience expects detailed information.

Tips for Aspiring Technical Writers: Technical writers should deeply understand their target audience’s knowledge and needs. Tailor your writing to provide information that is accessible and useful to the intended readers.

3 Style and Tone: Fine-tune Your Style and Tone

Content Writing: Content writers have more flexibility in choosing their style and tone. Depending on the subject and target audience, they can adopt a conversational, formal, or even humorous approach.

Technical Writing: Technical writing demands a consistent, formal tone. Clarity, accuracy, and objectivity are essential, and the focus is on delivering factual information.

Tips for Aspiring Technical Writers: Learn to adapt your writing style and tone to technical documentation requirements. Consistency is vital to ensure that your technical documents are clear and professional.

4 Subject Matter: Become a Subject Matter Expert

Content Writing: covers various topics, from travel and lifestyle to personal development and opinion pieces. They often choose subjects that have general interest.

Technical Writing: Technical writers focus on specialised subjects, such as software manuals, engineering documents, or scientific reports. They require in-depth knowledge of the subject matter.

Tips for Aspiring Technical Writers: To become a technical writer, start by building expertise in a specific field or industry. In-depth knowledge is crucial for producing accurate and valuable technical documents.

5 Research: Engage Yourself in Research to Know Your Topics

Content Writing: Content writers may require research, but it’s often limited to gathering general information and sources for reference.

Technical Writing: Technical writers rely heavily on research, often involving subject matter experts, engineers, or extensive documentation to ensure the accuracy of the information.

Tips for Aspiring Technical Writers: Develop strong research skills to gather and verify technical information. Building a network of subject matter experts can be invaluable in your technical writing career.

6 Formatting: Fix the Formatting of Your Writing

Content Writing: Content writers primarily focus on creating visually appealing content, which may include images, videos, and interactive elements to engage the audience.

Technical Writing: Technical documents often have a standard format, including headings, subheadings, lists, tables, and diagrams to enhance clarity and facilitate reference.

Tips for Aspiring Technical Writers: Familiarise yourself with standard technical document formats, such as headings and lists. Proficiency in document formatting tools like Microsoft Word and PPT and authoring tools such as Adobe Frame Maker, Adobe RoboHelp, and MAdCap Flare can be a valuable skill.

7 Review and Editing: Create a Review and Editing Workflow

Content Writing: Content writers often rely on self-editing or the services of general editors to polish their work.

Technical Writing: Technical documents undergo extensive peer reviews and subject matter expert scrutiny to ensure accuracy and clarity.

Tips for Aspiring Technical Writers: Embrace a rigorous review process for your technical documents. Seek feedback from experts and colleagues to refine your work and eliminate errors.

8 Terminology: Know Your Words Better to be Direct and Concise

Content Writing: Content writers use everyday language and may employ metaphors and similes to make content relatable.

Technical Writing: Technical writers use specialised terminology relevant to their subject, ensuring precision and clarity.

Tips for Aspiring Technical Writers: Master the jargon and terminology of your chosen field. This is essential for communicating effectively with professionals and conveying complex ideas accurately.

9 Document Structure: Learn the Skills of Document Structure

Content Writing: Content writers have creative freedom in structuring content, allowing for a more fluid and narrative approach.

Technical Writing: Technical documents often follow a structured and linear approach, providing step-by-step instructions or presenting information logically.

Tips for Aspiring Technical Writers: Practice creating structured, logically organised documents. Developing the skill of crafting clear and intuitive document structures is essential for technical writing.

10 Purposeful Graphics: Play with Graphics Carefully, Neither Less nor More

Content Writing: Graphics and visuals are often used for aesthetics and engagement.

Technical Writing: Graphics, such as flowcharts, diagrams, and technical illustrations, are purposeful and serve to clarify complex information in technical writing.

Tips for Aspiring Technical Writers: Learn to create compelling visuals that enhance the understanding of technical content. Graphics should complement the text and make it more accessible.

Conclusion:

Becoming an expert in technical writing is an achievable goal with practice. Understanding the differences between content and technical writing is the first step towards success. Aspiring technical authors can speed up their journey and become proficient technical writers in just one week by prioritising clarity, mastering subject matter, and developing technical communication skills.

Remember that practice is essential, and continuous improvement is the key to mastering the art of technical writing. Embrace feedback, refine your skills, and keep learning about your chosen field to produce high-quality technical documents that educate and inform effectively.

Navigating the Jungle of Contracting: A Tale of Missed Checks and Shouted Specs

Ah, the life of a contractor—where every day is an adventure, and you’re the hero armed with nothing but your wits and a laptop. Like Indiana Jones, I’ve managed client expectations and communication challenges. Here’s the lowdown on surviving the wilds of workplace woes with a grin.

Chapter One: The Case of the Missing Validity Checks

Once upon a time, I suggested to a Project Manager (PM) that we should probably check the content of a PowerPoint display before chucking it into the gaping maw of Confluence. He, in his infinite wisdom, proclaimed such checks unnecessary. “Just migrate it!” he declared. So, migrate I did. Mere days later, he scrapped the content himself because—plot twist!—it was outdated. Who could’ve guessed? Well, me… I did guess. However, in later collaborations, he had a sense of humour failure and raised his voice in frustration more than once.

Chapter Two: The GDPR Fiasco

Imagine, if you will, a GDPR project where the document looked like a horde of angry red pen-wielding vandals had attacked it. I dared to point out that the riot of track changes made the document as readable as ancient hieroglyphs without a Rosetta Stone. The PM’s reaction? A not-so-mighty roar in front of a dozen coworkers. Yikes! One week later, unable to cope, he walked away.

The Golden Rule: Set Expectations Like Setting Traps in the Jungle

To keep the wild beasts at bay (read: client frustrations), start every project by setting crystal clear expectations. Draw them a map with X marks on the spot, showing timelines and task breakdowns. Clients who know what to expect are less likely to go on a rampage when deadlines sneak up on them.

Educating the Natives (I Mean, Clients)

Empowering your clients goes a long way. Show them the path you’ve charted, step-by-step, so they feel part of the journey rather than just baggage being lugged around. It turns suspicious glares into nods of approval and keeps the peace in the village.

Broadcasting Updates: Not Just for Sports Channels

Keeping clients in the loop with regular updates is crucial. It’s like sending smoke signals to assure them that the project is still on fire (in a good way). This constant connection is the secret sauce to a successful client relationship; communication, not telepathy, keeps things smooth.

The Art of Feedback and the Grace of Boundaries

Allow space for feedback—it’s like a safety valve that lets off steam and realigns tracks as needed. Also, be like a serene monk when confrontations arise: acknowledge the thunder, but don’t let it shake you. Stick to your quality guns, and don’t let yourself be rushed.

Dealing with Workplace Wildlife

When faced with a fuming boss or a power-tripping manager, remember, it’s not just about surviving but knowing when to pack up your tent. Whether it’s taking your grievances to HR or simply walking away, choose your battles wisely.

In Conclusion: Be the Contractor Who Wrote the Book

Contracting isn’t just about delivering spiffy spreadsheets and snazzy slides; it’s about crafting an experience so transparent and smooth that even the most demanding clients want to bookmark you for a sequel. So there you have it, a guide to thriving in the contracting jungle—may your communications be clear and your expectations managed like a pro!

UX Writer v Technical Author

UX Writer Skillset Checklist:

Writing and Editing Skills
  • Ability to write clear, concise, and compelling copy
  • Grammar, punctuation, and style proficiency
Editing and proofreading skill
  • Ability to write clear, concise, and persuasive copy
  • Grammar, punctuation, and style proficiency
  • Editing and proofreading skills
User-Centred Design Understanding
  • Knowledge of UX principles and design thinking
  • Ability to create content that enhances user experience
  • Proficiency in developing user personas and journey maps
Research Skills
  • Competence in user research and usability testing
  • Ability to analyse and interpret user feedback
  • Skill in adapting content based on research findings
Technical Proficiency
  • Familiarity with design and prototyping tools (e.g., Sketch, Figma)
  • Basic understanding of HTML/CSS
Collaboration and Communication
  • Ability to work with UX designers, developers, and product managers
  • Strong interpersonal and communication skills
Project Management
  • Time management and ability to meet deadlines
  • Experience with agile and scrum methodologies
SEO and Analytics
  • Knowledge of SEO best practices
  • Ability to use analytics to inform content decisions

Technical Author Skillset Checklist:

Technical Writing Skills
  • Expertise in creating clear and informative technical documents
  • Ability to explain complex information in a readable format
  • Proficiency in document structuring and technical editing
Research and Analysis
  • Strong ability to gather and analyse technical data
  • Skill in interviewing with subject matter experts
Technical Knowledge
  • Understanding of the technology or products being documented
  • Ability to learn and understand new technologies
Documentation Tools
  • Proficiency in technical writing tools (e.g., MadCap Flare, Adobe RoboHelp)
  • Knowledge of version control systems (e.g., Git)
Attention to Detail
  • High level of accuracy and attention to detail in technical descriptions
  • Ability to maintain consistency across multiple documents
Project Management
  • Experience managing documentation projects
  • Ability to coordinate with various teams and stakeholders
Regulatory Knowledge
  • Understanding of industry-specific regulations and standards
  • Ability to ensure documents comply with legal and regulatory requirements

where do the skill sets of UX writers and technical authors crossover?

Despite having different purposes, UX writers and technical authors share critical skills in content creation.

  1. Clarity and Simplicity: UX writers and technical authors prioritise clarity in communication. UX writers focus on making interfaces intuitive and easy for users, while technical authors simplify complex technical information for readers.
  2. Audience Understanding: Both roles require a deep understanding of their audience. UX writers need to grasp user behaviour and psychology to craft user-centric content. Technical authors must understand their readers’ knowledge level and needs (often developers or technical users).
  3. Writing and Communication: Strong writing skills are essential for both roles. UX writers excel in concise and engaging microcopy (e.g., buttons, error messages), while technical authors write comprehensive documentation or manuals that are structured and informative.
  4. Empathy and Advocacy: UX writers and technical authors advocate for their users or readers. UX writers ensure that user needs are met through language and interaction design, while technical authors advocate for precise, accurate information that helps users achieve their goals.
  5. Collaboration: Collaboration with designers, developers, and subject matter experts is crucial for both roles. UX writers work closely with designers to integrate language into the user interface, while technical authors collaborate with engineers and product teams to gather accurate information.
  6. Research Skills: Both roles require research skills, though the focus differs. UX writers research user behaviour, conduct usability tests, and iterate based on feedback. Technical authors investigate technical facts, write about procedures, and ensure accuracy through testing and peer review.

While these roles have distinct purposes and outputs, professionals in both fields benefit from a combination of linguistic proficiency, user empathy, technical aptitude, and a commitment to clarity and simplicity in communication. This overlap allows for a fluid exchange of skills and knowledge, especially in interdisciplinary teams that create user-friendly products and comprehensive documentation.

Employers can use this checklist to assess the skills and suitability of potential UX writers and technical authors for their teams.

The Art of Bad Technical Documentation: Explained by a Technical Author to a Manager

Dear Manager,

As the dedicated technical author, let me take you through the “Art of Bad Technical Documentation.” Buckle up because we’re exploring the pitfalls and perils of wrong documentation. Here’s why your documentation is ineffective:

Embrace Ambiguity: The Clarity Conundrum

Why be clear when you can be vague? Inadequate documentation thrives on ambiguity. Instead of providing specific instructions, opt for terms like “thingamajig” and “whatchamacallit.” This keeps users guessing and adds an element of mystery to their experience. Remember, a little confusion goes a long way!

Skimp on Details: The Sparse Symphony

Who needs comprehensive information? Give users enough to make them think they understand, but more is required to accomplish their task. Skip critical steps and assume everyone knows what you mean. For instance, “Attach Part A to Part B” works perfectly without mentioning the dozen screws and the exact alignment required. Less is more!

Organise Chaotically: The Disarray Dance

Create a comprehensive setup guide with troubleshooting tips, installation instructions, and advanced features. This will ensure users spend more time searching for information than using the product. Plus, it will turn your documentation into a treasure hunt—fun—fun, right?

Prioritise accuracy: The Error Extravaganza

Facts are boring. Spice things up with outdated or incorrect information. If a user follows the steps and things don’t work, it adds excitement. Who needs up-to-date screenshots or correct commands? Keep them on their toes and guessing!

Overwhelm with Jargon: The Terminology Tango

Fill your documentation with as much technical jargon as possible. If a user doesn’t have a Ph.D. in your field, that’s their problem. Avoid plain language and never define terms. This creates an elite club of those who “get it” and keeps the riffraff out.

Bore to Tears: The Monotony Marathon

Write your documentation like a legal contract—dense, dry, and devoid of any engaging elements. Forget about headers, bullet points, or visuals. Walls of text are your best friend. If your readers fall asleep halfway through, you know you’ve done a successful job.

Ignore Accessibility: The Inclusion Illusion

Accessibility? What’s that? Ensure your documentation is as unfriendly as possible to those with disabilities. Tiny fonts, poor contrast, and a lack of screen reader compatibility are essential. After all, catering to everyone’s needs is just too much work.

Conclusion: The Hallmarks of Bad Documentation

In summary, inadequate technical documentation is an art form that requires a special touch. By embracing ambiguity, skimping on details, organising logically, prioritising curacy, overloading with jargon, boring your audience, and ignoring accessibility, you, too, can create user guides that are as entertaining as they are frustrating.

So, let’s raise a glass to the fine art of lousy documentation. Here’s to keeping our users on their toes and ensuring our tech support team never runs out of work.

Scene: A Discussion Between a Technical Author and a Manager

But have you recently checked the Helpdesk call stats?

How often have you considered the conversation you want with a manager without respect for the written word? When you do, will it go something like the content below? So, let’s read A Discussion Between a Technical Author and a Manager.

Characters:

      • Technical Author (TA)
      • Manager (M)

Setting: A corporate office in the manager’s office. The room has a large desk, a computer, and bookshelves filled with documentation manuals.

TA: (looking concerned) I’ve been reviewing our latest product documentation and must say it could be better. Numerous inaccuracies make it hard to follow and lack coherence. Our customers have been quite vocal about these issues.

M: (dismissively) I think you’re overreacting. Our documentation is excellent, and customers always find something to complain about.

TA: (patiently) But the complaints are consistent. They mention the same problems: unclear instructions, lack of coordination between sections, and poor flow. These are not just one-off comments; it’s a trend.

M: (irritated) Our customers don’t understand the product. They’re not exactly the brightest, you know. If they can’t follow simple instructions, that’s on them, not us.

TA: (firmly) I beg to differ. Our job is to make the documentation clear and accessible. If multiple customers are struggling, we need to address that with urgency. Documentation is crucial for customer satisfaction and retention.

M: (defensive) We’ve been doing it this way for years. We can’t change everything. Besides, rewriting everything would be a massive waste of time and resources.

TA: (calmly) Consider this: poor documentation already costs us time, money and resources. Also, our contract of delivery states we will supply up-to-date documentation. If a customer reads that, we could find ourselves up to our necks in a lawsuit for providing defective user guides. Another point: I read in a trade magazine our software ranks number 10 out of fifteen competitors, and our company is haemorrhaging cash. I also know you have contracted three more help desk pros to help with the increased demand for the increasing number of calls. But have you checked the Helpdesk call stats lately? They are still overwhelmed with more calls and emails that we could avoid with better documentation. The other day, they were fielding One call every ten minutes, and many calls were from the same customers becasue our help desk needed to know the answer. With every iteration of our software with more add-ins, our customers need help finding solutions that our software promises to fix. And our frustrated customers are turning to our competitors. Better documentation will help the support team. It works two ways.

M: (reluctant) So, what do you propose?

TA: Let’s start by conducting a thorough review of the documentation. I’ll work closely with the product team to ensure we capture all the details accurately. We can reorganize the content to improve the flow and clarity. We should also get feedback from some loyal customers before finalizing anything.

M: (sceptical) And you think that will make a difference?

TA: (confidently) Absolutely. Clear and well-structured documentation can significantly enhance the user experience. It reduces the need for support, increases customer satisfaction, and leads to better retention and word-of-mouth.

M: (sighs) Alright, fine. Let’s give it a shot. But I’m holding you responsible for this. If it doesn’t work, it’s on you.

TA: (smiling) Fair enough. I’ll get started right away.

M: (grudgingly) Make sure it’s worth it.

TA: (determined) It will be. You’ll see.

Narrator: The technical author embarked on a mission to overhaul the documentation. The technical author transformed the documentation into a clear, comprehensive, user-friendly guide through meticulous effort and collaboration. Customer complaints dwindled, support requests decreased, and satisfaction soared. Despite resistance, the manager couldn’t deny the positive impact of the improved documentation. The technical author had indeed saved the day.

How to Win Over Management and SMEs: A Hilarious Guide for Technical Authors

So, you’ve embarked on the noble quest of a technical author. Your mission, should you accept it (and you have no choice), is to convert the mighty management and the enigmatic SMEs (Subject Matter Experts) to your way of thinking. Sounds like a Herculean task? Fear not! Here’s your humorous guide to charming them into submission while keeping your sanity intact. Remember, we’re all in this together, united by the common goal of effective communication. So how to Win Over Management and SMEs to your way of thinking.

Speak Their Language (No, Not Klingon)

Let’s be honest—management speaks in KPIs and ROI, while SMEs converse in an ancient dialect known only to a few. Your first step is to become a polyglot. Learn to weave your documentation magic into business objectives and arcane technical details. It’s like being a translator at the United Nations but with less chance of starting an international incident.

The Art of Presentation: Smoke and Mirrors

With communication, clarity icriticaley. But why stop there? Make your points with the flair of a Las Vegas magician. Use charts, graphs, and infographics that sparkle. And remember, nothing says “I know what I’m talking about” like a well-timed meme. Trust me; pie charts are irresistible to management as cat videos are to the internet. Please don’t overdo it, or you will end up in a meme yourself!

Quick Wins: The Fast and the Furious

Management loves results faster than a pizza delivery. And who’s the hero delivering those results? You, the technical author. Identify accessible opportunities and deliver those quick wins like Vin Diesel in a muscle car. A tiny tweak will save an hour of work each week or a new tool that doesn’t require a PhD. Shout about those victories with the enthusiasm of a game show host handing out prizes. You’re the star of this show.

Collaboration: Herding Cats, but With Treats

Getting management and SMEs to work together is like herding cats, but don’t worry—we have treats! Engage them early with workshops that are part of brainstorming and therapy sessions. Provide plenty of coffee and snacks; they’re more likely to engage if their blood sugar levels are stable. Plus, who argues over a cookie?

Build Relationships: Be the Office Barista

Relationships are everything. Become the office barista—always ready with a listening ear and coffee. Trust and rapport are your best friends. Remember, it’s harder to say no to someone who knows your coffee order by heart.

Highlight Long-term Benefits: The Crystal Ball Approach

Paint a picture of a future so bright they’ll need shades. Highlight how your approach will lead to fewer headaches, lower costs, and maybe even a tropical vacation (we can dream). Show them the long-term benefits with the enthusiasm of a late-night infomercial host. “But wait, there’s more! If you adopt this strategy now, you’ll also get…”

Embrace Technology: The Cool Kid in School

Introduce new tools and technologies like you’re showing off the latest gadget. Be the cool kid who knows all the shortcuts and secret features. Offer training sessions, but make them fun—think less “seminar” and more “techno party.” Bonus points if you can throw in a few tech-related jokes. “Why do programmers prefer dark mode? Because light attracts bugs!”

Example Scenarios:

      • Scenario 1: Management Concerned About Cost: “Dear Management, investing in this new tool is like buying a golden goose. It’s pricey upfront, but think of the endless eggs. In financial terms, that means reduced time, fewer errors, and overall productivity that will make our competitors weep.”
      • Scenario 2: SME Resistance to Change: “Dear SMEs, we know you love your ancient rituals, but imagine a world where documentation is a breeze. Join our workshop—there will be snacks!—and let’s create a workflow so smooth, you’ll forget what life was like before.”

Ultimately, winning over management and SMEs is about strategy, charm, and humour. So, arm yourself with these tips and spread the word about the importance of good documentation. Keep in mind that these strategies have been tried and tested. If all else fails, remember that bribery with baked goods is always an option. With these tools, success is inevitable.

How do you manage a knowledge base for a project in the development phase.

Managing a knowledge base for a project in development is not just a task, but a crucial step towards empowering every team member with time-saving information. So, how do you efficiently manage a knowledge base for a project in the development phase? Here are some steps to handle this:

  •  Centralised Knowledge Repository
        • Choose a platform: Select a platform that suits your team’s needs. Options include Confluence, Notion, SharePoint, or a well-organised GitHub repository.
        • Organise Information: Create a structured outline with categories, such as
          • project overview,
          • technical documentation,
          • meeting notes,
          • feature specifications, and
          • troubleshooting guides.
  • Documentation Standards
        • Define Standards: Establish documentation standards and templates to ensure consistency. Include guidelines for writing style, formatting, and required sections for each document type.
        • Regular Updates: update documentation to reflect the latest developments and changes in the project.
  • Version Control
        • Track Changes: Remember to use version control for technical specifications and code, using tools like Git or integrated features in platforms like Confluence. Version control enables you to track document changes throughout their lifecycle, making it easier to revert to a previous version if necessary. 
        • Change Logs: Maintain a change log to record significant updates or revisions to the documentation.
  • Access and Permissions
        • Set Permissions: Define who can view, edit, and manage different knowledge base sections to maintain control and prevent unauthorised changes. Do this through the platform’s settings or by assigning roles to team members.
        • Ease of Access: Ensure the knowledge base is easily accessible to all team members, with intuitive navigation and search functionality.
  • Collaboration and Feedback
        • Encourage Contributions: The knowledge base is not just a repository of information, but a collaborative space. It’s a place where every team member can contribute, fostering a sense of camaraderie and shared responsibility. Implement a review process to ensure the accuracy and quality of the contributions. 
        • Feedback Mechanism: allow team members to provide feedback on the documentation, suggesting improvements or reporting issues.
  • Training and Onboarding
        • Onboarding Materials: Create onboarding materials for new team members, including guides on how to use the knowledge base and where to find critical information.
        • Training Sessions: Conduct regular training sessions or workshops to ensure all team members know the knowledge base and its importance.
  • Integration with Development Tools
        • Tool Integration: Integrate the knowledge base with your development tools (e.g., Jira, Slack, Trello) to streamline workflows and ensure documentation is part of the development process.
        • Automation: Automation updates documentation based on project management tools or codebase changes.
  • Regular Audits and Maintenance
        • Periodic Reviews: Schedule regular audits of the knowledge base to ensure the information is still relevant and up-to-date and the accuracy and relevance of the information you rely on.
        • Clean Up: Remove outdated or redundant information to keep the knowledge base lean and valuable.