Tag: working with a technical writer

Technical Authors what we are and what we are not

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.

What I or WE are NOT

Software Developer

If I had proficiency in BASIC, C/C++, Java, et cetera, I would earn significantly more as a developer. I receive calls for API documentation, a skill requiring familiarity with the code.

Project Manager

I will be careful here. I am not a project manager certified through Prince2, Agile Scrum, etc. My PM skills apply to technical documentation, whereby I set my schedule and arrange meetings with SMEs and other stakeholders. 

Beyond documentation, my PM skills do not stretch to:

      • The provision of detailed project planning, including progress evaluation, risk management, issue and resolution. If that is essential, hire a full-time project manager.
      • A secretary organising the working lives of colleagues and taking minutes. I record my meetings (with a dictaphone) and extract the relevant information for the documents.

Technical authoring is lengthy, and additional expectations could delay my progress. It’s time to open the heads of SMEs to extract all that hidden information. I then use it to build a document explaining to your non-technical audience how it works.

While I will be familiar with the terminology, remember I am not an expert in your department. I learn on the job. 

I am skilled in facilitating communication and collaboration through effective verbal and written communication. I provide support and encouragement to help achieve goals, and the process is not as daunting as it may seem.

I’m a third party.

As an external consultant, I decided, after a period of reflection on your situation and expectations, to use MoSCoW. That stands for four different categories of initiatives: 

      • must-haves, 
      • should-haves, 
      • could-haves, and 
      • will not have. 

The “W”, should you prefer, can mean wishful thinking. 

Let me have it.

When I join, please throw your documentation at me, everything, wherever it is, and let me sift through it all. I have my own Excel spreadsheets to track and control the documentation.

Define how to manage documents/content with SharePoint and Confluence. 

The efficient management of both applications improves the information available to your teams.

By now, I know where the knowledge gaps are where I can improve the documents and start working with your SMEs. 

Project Management 

As mentioned above, I possess the relevant skills within the context of a technical author. 

      • Design new template
      • Improve the structure of existing documents
      • Process documentation across several categories,
      • Arrange meetings with SME’s,
      • I use tried and tested methods to plan, write, review, publish, and maintain the content.
      • Write/update the documents.
      • Procedures and processes updates,

An aid to content development

With over 23 years of experience behind me, I already own an extensive library of generic documentation and various templates. If you have no documentation, we can tweak any document to meet your business profile. It saves not only time but also money. 

ITIL and ITSM

I have experience in producing the following document types: 

      • IT Service Management (ITSM) based on ITIL best practices. Level 1 to 4 BPMN VISIO Processes and Narratives.
      • Service Design, Service Transition, Service Operation and Continual Service Improvement,
      • Delivery and Service Support, 
      • Availability, 
      • Capacity, 
      • IT Service Continuity Management; 
      • Incident, 
      • Problem, 
      • Change, 
      • Release, 
      • Configuration Management and 
      • Service Desk.

Policy and Process

      • Delivering written Policy, Process & Standards
      • ISO27001/9001 compliance documentation to support a company’s GDPR, PCI/DSS, security project
      • Documentation to support a disaster recovery scenario

Infrastructure Documents

      • Operating infrastructure documentation to support the functions of a large-scale network
      • A documentation suite to help IT teams manage a recently migrated infrastructure.

Editing Existing Content

Enhancements may include: 

      • adding VISIO drawings,
      • new screenshots,
      • reword policies and content per se,
      • additional narrative to processes that are light on information,
      • new templates, and
      • Structure to existing Word documents and consistency. 

All information needs a peer review by people who should know the data best and provide feedback. I leave nothing to chance to get what you need in place. 

Tools

Apart from spreadsheets, MS Word, PowerPoint, and VISIO, my skills keep these projects on track. I will also suggest ways in which you can keep the documentation up-to-date and current. Information is an asset, and without it, you could place the business at a disadvantage.

SharePoint and Confluence

Suppose you have no official documentation strategy or a way to manage the documentation. If so, let me create a plan that will work for you. Documentation must be available to all staff and updated, rewritten, and archived appropriately. Ownership, version control, and historical control are other aspects that need managing.

If the business uses Confluence, my experience on a client site is an overload of outdated content irrelevant to the company. I can analyse all spaces and check when the content was written and submitted. 

Expectations

There are too many to mention, but the immediate impact will be on the following three points:

      • Reduced costs
      • more responsive help desk/support 
      • better informed staff
      • Confidence in performing procedures.

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.

%d bloggers like this: