January 22, 2021

Learning Structured Authoring: Tips From an Engineer

Share
image shows a person teaching another structured authoring

Sharing my Mindset

Technical communicators, documentation specialists, technical content writers – we all come from different professional backgrounds. No matter whether we specialize in pharmaceuticals, transportation, or APIs, we all strive for the same thing: how to communicate effectively in an organized and efficient manner.

One of the challenges of the job is that many of the tools we use daily are hard to learn and take time to develop expertise. So it is no surprise that many in our industry look at “structured authoring” with the fear that it is yet another huge time sink with dubious returns. But from my experience, I believe anyone can learn it, and the time you will save is absolutely worth the onboarding! My background as an engineer just happens to facilitate the learning curve a little more than most.

After all, “structured authoring” just means “organized information!”

An Engineer’s Recommended Steps to Using Structured Authoring Effectively

As technical writers, we know that structure and thoughtful planning leads to success when it comes to our documentation. This is especially true when collaborating within a team. Even with proper planning, it takes a lot of thought, time, and effort to ensure consistency (not only in formatting, but in content messaging as well). That is the beauty of learning structured authoring – it makes it easier to deliver consistent content. Structured authoring sets boundaries that facilitate consistent structuring across different types of content, with far less manual effort.

Like many writers, you may be intrigued by the possibilities of learning structured authoring, but find it daunting to learn. I have to admit I had an advantage when I first started – I am an engineer-turned-writer, and so the idea of structuring content itself came naturally to me. That is why I want to share the steps I developed from my engineering mindset that can help you approach structured authoring for the first time. These steps are the building blocks that helped me to reach documentation success while implementing (and enjoying the benefits of) structured authoring.

Again, I would like to emphasize – my training as an engineer is certainly no prerequisite to success with a modern structured authoring tool!

Step 1: Determine Publication and Topic Relationships

The first step is to plan out your documentation relationships. Think about which documents are related, and what the specific, individual topics are within each of those documents. I find it helpful to draw out the relationships between all of my documentation. I list all of the related titles, and then list out their topics (which are generally their individual tables of contents) as bullet points.

Connect any matching or similar topics with a line. With this method of topic research, you will quickly see which documents and publications use the same topics. These topics will become the material that will be reused in multiple publications.

Step 2: Topic Organization and Development

Now that you have an idea of what topics are used and reused across different documents, it is time to develop your topic organization. How are you and other writers going to find out if a topic you need already exists? Think about how you can categorize your topics for easy reference and usability. With a CCMS (component content management system) like Paligo, you can organize your topics into folders and use taxonomy labels.

Taxonomy labels are an effective tool because topic organization has many solutions. In other words, not everyone would organize the topics into identical folder structures that you would set up. But with taxonomy labels, any team member can find all the topics that share the same tag, despite folder location. For example, if your teammate put specification details into different product folders and added the taxonomy label “Specifications” to each topic, you can easily view all of the product specifications without having to search through the folders.

Writing the Topics – and Tools to Help

When writing a topic, it is important to consider how the content you are writing will be reused. Each topic should be short and specific – this helps ensure reusability across many different publications. Of course, there may be circumstances when different publications require very similar content that has specific differences. This is where block elements, variables, and filters come in handy.

Block Elements

Not only can you reuse topics in Paligo, but you can reuse pieces of content from within them. These pieces of content are called block elements. Block elements can be searched for and reused as needed. For example, if you only need one para from a topic for another topic, you can copy and paste that specific element (the para) as reused into the new document or topic. When pasted as reused, this specific para is locked and cannot be edited. When it is unlocked and edited, this para is updated everywhere it is reused, eliminating the need to find and update it in other topics or publications.

Variables

Variables are specific pieces of information that can have multiple inputs. You can think of these as a placeholder for specific information. Variables are very useful in documentation that you want to use for multiple products that share the same defining parameters. For example, consider product documentation about a car. Some examples of variables might include max. speed, mileage, and color. You can set the variables “Speed,” “Mileage,” and “Color” to have multiple inputs that match up to specific cars. Upon publication you can choose which car the publication is about and Paligo will automatically fill in all of that car’s information (wherever you used the variables “Speed,” “Mileage,” and “Color”). You can then publish that same document but choose a different car and it will automatically fill in the parameters that define that second car’s performance.

Filters

Filters act as (unsurprisingly!) filters to specific pieces of information in reused topics. These filters are helpful if you want to reuse a topic but need to add language that is only applicable to specific instances. Filters also allow you to reuse topics and eliminate elements that are not applicable to your publication. This means none of the topic’s elements are removed, but only the applicable elements are shown in the final publication.

Step 3: Recycle Topics Across Publications

This step is my personal favorite – reusing topics across different publications. As you develop your documentation, if you carefully planned your publication relationships you will be able to start a document and pull in all of the source material topics you already developed. In other words, you can assemble much of the document from the modules of content you already have. By reusing topics in conjunction with block elements, variables, and filters, you have effectively eliminated the need to start any document from scratch.

You and your team will be rest assured knowing that every single publication that uses the same topics is consistent. This is because the topics are not copied and edited separately, but linked to a single, continuously updated source. When any content needs maintenance, all of the related publications that use that maintained topic will automatically be updated instantly. Now that’s what I call efficiency!

Final Notes on Learning Structured Authoring

Although you may have felt overwhelmed at the thought of learning structured authoring, it is my hope that these steps and tips help you in your initial efforts. Learning structured authoring – specifically, Paligo – has shifted my own view of how content can be assembled. I now regard documentation at a higher strategic level of relationships and reusability that saves me hours of unnecessary work. If you find the task of learning this new tool overwhelming, try following the above steps and practice – it is well worth the effort in evolving how you think about documentation development! Watch our interview series on “Structured Authoring” here.

Share