Tech Writer Today’s Technical Writing Tips and Tricks column is brought to you by Adobe Systems, Inc. Download a 30-day free trial of Adobe FrameMaker here.
As you begin to explore structured content and how you can leverage it for your organization, you’ll need to consider quite a number of things. Not the least of these is what structured model to use. You’ve probably heard of standards like DITA, ATA specifications, S1000D, and others. Depending on your industry, client base, and even the staff you have and their skills, any one of them might be a valid approach.
What many people don’t realize is that the structured model you choose affects the ability to make your conversion process as seamless as possible. To that end, I suggest that you take time to think about the standard that works best for you, and then perform a proof of concept with some of your existing content to understand your ability migrate to that standard.
When you complete this exercise, you end up with materials that are representative of the work that your organization does reworked into a structured model. Not only can you see how your content fits in the model, you can explore how this model works with your processes and people… and, of course, your tools.
This is where source content authored in a tool such as Adobe FrameMaker really shines. Since the software is already able to work with structured content, including both DITA and S1000D, a sample conversion results in a good taste of the future. With a bit of training (usually one to three days) on working with the structured model, your writers can experiment with content they know and begin to dive in a bit deeper.
The format likely won’t be what you specifically expect, but that’s an easy fix (well, mostly an easy fix). FrameMaker uses a document called an Element Definition Document (or EDD) in which the structured rules and the format rules are connected. You apply the EDD to a template, and that template can be used to create content, format content, and edit content. Happily you can do all of this while remaining within a structured workflow AND having a visually rich work environment that your writers recognize. As a bonus, if you are NOT in FrameMaker, there are plenty of options to rework Word content into FrameMaker, if you want to use that as a way to work with structure.
In this illustration you see an excerpt from an EDD. In this case the element named Title is configured to use a contextually sensitive format. If the element is contained within a table then the paragraph tag TableTitle is used, if in a Section the format Heading1 is used, and if in a Chapter the format Title is used. This means you can reuse your FrameMaker templates when moving to structure and save time, effort, and money on building custom stylesheets.
Yes, you should expect to expend some effort— it’s not “just click a button and you are done,” but you’ll have to do some work no matter which tool you’re working with. You can’t just “click a button” and migrate Word to an XML ready format. And, you can’t just “click a button” and completely reformat a document into an online deliverable. Before you click that button, you’ll need to do setup and programming and testing and configuration and discussion and… Well, you get the idea.
So what DO you need to do to migrate your content to structure? Regardless of your structure, you’ll need to undertake some initial steps to ensure a successful effort:
Review your Existing Content
If you don’t know what you have, what shape it is in, and where it is going, then you likely aren’t going to get any benefit from structured content. Do a detailed review of the materials you have. Identify what has a “future life” and what is obsolete and no longer needed. Also review it for consistency, and investigate how the content is created and managed currently. A few of these questions include:
- How many writers created, edited, or otherwise worked with the source?
- Did they use a style guide (and was it a good one with clear instructions)?
- Do you see repeated patterns in content (for example, the style/tag WindowName was used to format the words that identify a dialog box title every time)?
- Are your templates consistent in the way they are used (or did people open them, and then do whatever they wanted to make it “look right”)?
Review your End Goal
If you don’t know where you are going then it’s really tough to map out how to get there. By having an idea of WHY you are moving to structure, and understanding what you have to gain, you can better understand both how to get there AND what you can gain. That means asking more questions, such as:
- What’s will you gain by converting to a structured standard?
- What output types do you need (PDF? Mobile? Web? Help? All of the above?)
- How will the output be generated?
- Who uses the resulting structured content: just writers? Partners? OEM vendors? Others?
- Do you plan to translate the content?
- Will you need a content management system?
Review your Plan
By now you should see that you need a plan. That plan should include learning all you can about how structure works broadly. You also need to explore a few standards and have an idea of why they are used, who uses them, and what you can gain by using them. Technically, you can even build your own, but usually it’s better to first see what others are doing. After all, we don’t often decide to go out and build our own house, our own car, or even our own computer (anymore). We also don’t milk the cows, manage our own investments, develop our own medicine, or repair our own gas furnaces (or at least not without research, training, and more research and training).
Not only should your plan include understanding what’s available, it should include answers to where you are, and where you want to go. Once those are in place you can begin to explore HOW to convert content to structure. The answer to How, of course, is a long story as well.
Learn More
You have lots more learning to do after you do your initial research and start your migration effort. Fortunately, you have lots of resources to choose from: Work with trainers and consultants who can help: Join mailing lists and discussion boards. Attend a few conferences. Download videos—of of the conversion process, the author tools, the content management systems, and a lot more. The options are almost as limitless as the questions that will come up along the way.
I recommend finding a consultant with a good track record and clients who speak well of the work that gets done. Spend the time and money upfront to have someone outside your organization get to know your situation and help to identify if you are considering the right model for the right reasons. If so, request a small demo of your content converted to the most applicable structure. Then review that content under multiple scenarios (the format doesn’t matter… the look and feel can change as needed based on the role of the person working with content, the tools available, and even the device used to view content).
