Capturing information and crafting content

“I KEEP six honest serving-men
(They taught me all I knew);
Their names are What and Why and When
And How and Where and Who.”

– Rudyard Kipling

This excerpt from a poem by Kipling is about curiosity – the willingness to learn to ensure understanding. Journalists are taught to look for Kipling’s “six honest serving-men” when researching a story. And it’s no different for us Technical Authors when capturing information and crafting content. We use these same ‘six honest serving-men’ to consider:

• What: am I writing about?
• Why: am I writing this?
• When: would I need this?
• How: does it work?
• Where: is it relevant?
• Who: needs it?

From old hat to a brave new world

For 30 years I’ve used this process, mostly as a freelance author. It would be a similar routine every time. A blank canvas, sitting face-to-face with a Subject Matter Expert (SME) and beginning with the opening question: “So tell me what you need…” – and then the learning would begin. It may have taken an afternoon, a day, sometimes longer… and it wouldn’t end there. There would be something that I hadn’t thought about, maybe something I misunderstood. The requirement, the technology, and sometimes both, might be new to me. I would learn and be curious, but would be a student to a teacher whose job wasn’t to teach. The approach could be inefficient and sometimes, to the SME at least, bothersome.

These days I use a different approach. So what’s changed? Well, I’m no longer a freelance author. I’m now part of the 3di family of authors, and discovering how the search for Kipling’s honest serving-men is done differently. Very differently. And I’d like to share with you some of the things I’ve learnt.

There is no blank canvas

At 3di, there is no such thing as a blank canvas. Here, significant portions of the writing are already done thanks to in-house expertise and some quite clever tools.

Granted, there will always be some placeholders; areas of content specific to the tool, device or piece of software. But at 3di, we come into our own with a writing process that adheres to good practice and appropriate quality standard directives. And that gives us authors a head-start.

As an example, a hardware machinery project will already have in place approximately 90% of the safety information, and 50% of the hardware design structure, even before a site visit is organised. It will be correctly structured, appropriately styled and conform to relevant quality requirements.

But how is that done? Stand aside. Here come the solution designers, content models and style guides.

We get you…

At 3di, we approach technical documentation in a way that understands the specific needs of each client, and the solution designers create very specific information solutions to communicate that to the end user. It’s not about becoming product or service experts ourselves. That’s inefficient. It’s about understanding what the end user needs to know, and then applying that need to the solution. Who will be the consumer of the content? What is the context? Do they really need to know that? These initial questions not only confirm that there is a need for our services, but gives a clear indication of the type of solution required.

Hard hats at the ready!

When we begin to craft that solution, the building work begins almost immediately. The solution designers – or architects – have done their bit. This is where content models and style guides come into play.

A content model defines the framework on which the content is built. A bit like having a prefabricated foundation for a building. It shows how the completed publication will look, how many different sections, or rooms, there will be, and what their functions are – kitchen, bathroom or lounge.

A style guide, on the other hand, defines the feel of the documentation. The interior design element, if you will. The colours, the fonts, the words to use and the words not to use, and the way words and characters are written, graphics are drawn and videos play.  And if these need to be tweaked, it doesn’t stop content from being created. All that can happen in parallel. You can read more about using style guides here.

“Always plan ahead. It wasn’t raining when Noah built the ark”

– Richard Cushing

So the foundations are in place, the designs agreed, and the writing started, but what about those finer details to make the plans concrete? For this, we employ the aptly named ‘discovery session’ with the SMEs. The discovery session follows an agenda designed to capture everything needed to deliver the solution with minimum ongoing client contact, and with maximum self-sufficiency and sustainability.

Essentially, these are the key must-haves for a smooth production phase. And they can actually be split between essentials for understanding the project, and essentials for understanding the content:

This sets the wheels in motion to develop and agree on the workflow, which includes things like:

• Roles and responsibilities – who is doing what and when?
• Templates or blueprints – what has already been approved and tested?
• Content framework – how will the documentation be structured?
• Style guide details – what will the general look and feel be?
• Terminology strategy – how can we use terms consistently?
• Visual elements – how will images, screenshots and other visuals be used? (You can read more about using visuals here)

Have words, will travel

In 1997, Walmart opened up stores in Germany. Sounds pretty straightforward. Not so, culturally. Local customers just couldn’t get used to the US practice of cashiers packing their groceries for them. It scared off a lot of potential customers. So in 2006, and although not the only reason for the failure, Walmart shut up shop in Germany. The concept just didn’t travel. But what’s this got to do with writing words?

Well, there’s some clever “behind-the-scenes” stuff going on at 3di to make sure the content we produce will travel, and that’s an essential part of the content creation process. Is your product going nowhere, or do you have visions of a global market? We suspect the latter. So that’s why when we write, we are thinking about how the content will travel, or localization.  Preparing content for localization means not only making sure that the source content can be easily reproduced in different languages but also allows for cultural differences. So we need to think about:

• Fewer words
• Sensitive language
• Generic imagery
• Computer-assisted translation techniques
• Using suitably qualified native speakers to check the quality of the outcome

It might just be the difference between being able to buy Hershey’s in Hamburg, or not. So there’s a bit of “top-grade, unequivocal, ingenious insight” for you (or perhaps we should just say “information”).

Choose to reuse

It’s also important that we determine if we can integrate with content already being written. For example, API documentation needn’t be written from scratch if there are code snippets we can incorporate into the documentation from existing sources. If there is marketing or training material readily available to meld into concept placeholders, or CAD source files an illustrator can use to produce line drawings, let’s use these.

During this stage, an experienced authoring team like our writers at 3di, fall back onto their experience to help craft and complete a solution. If your team has experience in writing a specific type of documentation, whether it’s technical manuals for complex machinery, API documentation for developers, or user help guides for consumer goods, at 3di, we’ll already have an understanding of the detail needed, what the look and feel of the documentation should be, and how much input is necessary.

And we’re up and running!

All hands to the pump!

At 3di, we also use collaborative writing. That means using more than one author to produce a single piece of content. That’s many hands expanding the experience and knowledge base. Collaborative authoring enables better quality content to be created more efficiently, and overall it’s a more flexible and resilient process.

“Collaboration not only draws on the expertise and energy of different people but can also create an outcome that is greater than the sum of its parts.”

– Rise B. Axelrod and Charles R. Cooper

There are many methods of collaborative authoring that allow for this. By following agreed writing methods, standards and procedures, content is created quickly and efficiently, without sacrificing quality. If you’d like to know more about creating collaborative content, you can read this quick guide from my colleague George Lewis.

In conclusion

Getting complex – and sometimes even simple – documentation solutions designed, crafted and delivered can be fraught with complications, misunderstandings and hiccups along the way. But to get the job done successfully and smoothly, our team of writers at 3di use the skills and tools developed from years of experience. Using the head-starts we cover here – successfully employing existing templates, capturing essential information efficiently, using content models, style guides and product experience – can all result in a pain-free solution to producing quality documentation.

It’s true the last few years have been a challenging time for many of us, and for some, remote working has become the new norm. When face-to-face liaison is difficult or impossible, having an experienced authoring team that knows how to ask the right questions, and how to use the latest tools to their advantage can help you to produce useful documentation with the minimum of fuss. Yes, Kipling’s poem still applies – questions will need to be asked when capturing info. However, with good planning and preparation, the elusive six honest serving men are actually not so elusive after all.