Migration DIY

The project to migrate our content from our current tool to a new Content Management System is ongoing.

The system is installed and we are beginning to use it. Our goal is to migrate content between deadlines, so that we do not disturb the release process of the software products.

Migrating the content ourselves is a lot of work, but we discovered some benefits to the extra work.

Know the Content

We recently had personnel changes, so projects were moved around. Rewriting and reformatting allows the writers to really learn what content is in the projects. When done, they have gained valuable knowledge about what is written and what areas need additional writing.

Clean the Content

Because we know our products, we can assess the topics and update accordingly. We were able to clean the content during the reformatting into DITA, so this is more of an extension of that process. We are able to focus on what the customer needs and verify that our content contains the information in a clear way.

Reuse the Content

As we work with the content, we can find pieces of content that we can reuse: the phrases, sentences, and paragraphs that we use over and over. Often the words are not exact, and setting them up for reuse creates standard terminology.

We are building the libraries for these reuse items, and communicating it to the other tech writers. As we solidify the content in the new system, we will invite other teams to use chunks of the content.

It will take over a year to migrate all the content. But once we finish, we will have clean, strong content, and the writers will truly know the content. Those benefits are worth the effort of migrating the content ourselves.

Timely and Relevant

The technical publications department is still working to prepare our topics for migration to a content management system. We reformatted our topics into DITA. As we reformatted, we kept track of topics that we wanted to revisit for content. We are now reviewing those topics to see how they can be rewritten.

Point of view

The first thing we look for is the point of view. Too often, technical writers document the UI. Instead, they should document how users use the UI in their workflow. If more than one role uses the UI, do the roles use the UI in different ways? This could mean more than one topic is needed. Are there best practices or tips that can be added?

Relevant for Today

When functionality is first added to software, it is not fully tested within the users’ workflow. This is true even if UAT has been done. As the functionality is used within the workflow, users adjust their workflow to use the functionality in the most efficient manner.

This workflow can be different than what was envisioned by the development team, since it can include workarounds for defects or unexpected behavior. These can be covered in one topic or more than one, depending on the situation. Sometimes I incorporated unexpected behavior in a note, other times in a separate topic or troubleshooting topic.

Complete and Accurate

The final thing we look for is to make sure we have covered the whole functionality. Has anything changed in the functionality since the topic was first written? Details that were true when the functionality was first added can be inaccurate now due to defect fixes. Is the breath of the functionality covered? Now that it has been used within a workflow, do users use the functionality in a different way than expected? Are more tasks required to cover the use of the UI within a workflow?

As topics age, we need to review them so we can verify that they are still current based on how the user includes the functionality within the workflow of their role. This can include how users incorporate workarounds or changes to how the functionality was originally planned. As tech writers, we need to remember that even if the functionality is static, users are always looking for the most efficient way to do their work. As the workflow changes, we need to update our content.

DITA Explosion

The Technical Publications team has been hard at work DITA-fying our topics. We are 80% through our reformatting our legacy topics. Of course, any new topics are DITA. 

We discovered an interesting phenomenon: 

The number of topics exploded.

The number of topics has grown simply because we separated our topics according to DITA type. Each topic is ONE type. ONE concept. ONE task. ONE reference.

Previously, a topic might include the conceptual information in the introduction, the steps to more than one task, and the field limitations within the task. We buried details and unintentionally made it difficult to find information. Topics were long, requiring scrolling or paging to access the information.

DITA changed that. By reformatting into smaller, more structured content, information is now easily accessible.

Easy on the Eyes

Our topics are shorter and more concise. There is more white space. The user is not overwhelmed with too much information, scrolling less. Users can find the answer to their question faster, which enables them to solve their problem faster.

Focused Content

Once we separated the information into topic types, and placed one idea in each topic, the content of each topic was focused. Concept topics explain “who,” “what,” and “why” a user would do a task. Task topics explain “how” and “when”. Reference topics detail the “how”. The information a user wants is easily found and understood.

User Experience Level

Users can access information according to their level of experience. New users read the concept topics before attempting the tasks and rely on the references. Experienced users skip the concepts, but use the tasks and reference as reminders. Mature users skip the concepts and tasks to use the references to verify field limitations.

When we reviewed the new format with our stakeholders, we received positive responses. The training team and support team are pleased to see how clean the help looks. Topics now correlate with training. Support can refer to specific topics when they walk customers through issues. Our team finds writing much easier also. With the structure so clearly defined, we can focus on the ONE piece of information that needs to be conveyed in the topic.