Capturing information and crafting content
By Alan Maynard
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:
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.
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.
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.
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.
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:
|Project essentials||Content essentials|
|Reviewing and confirming the goals||Examples of priority use cases|
|Product and context overview||‘Getting started’ challenges|
|Regulatory context||Routine and non-routine actions|
|Product and documentation development timelines||Documents and other content|
that already exist as part of
|Access to additional information||Good and poor examples of documentation from existing products, competitors and 3di|
This sets the wheels in motion to develop and agree on the workflow, which includes things like:
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:
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”).
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!
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.
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.
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.
Alan works as a Senior Technical Author and is based in our Woking office. Early in his career, Alan developed an enthusiasm for the user experience side of technical writing. Away from Technical Authoring, Alan has been known to play guitar in various local groups, and dabbles in many sports, excelling in table tennis.