I’ve seen it first hand in several companies I have worked for: Field agents or other colleagues that work closely with individual customers come to me in the documentation department and ask me to make sure that their standard product documentation is always up to date. And then, they want to add a little bit of special information for each customer.

“Oh, and by the way. In the field agent office, we have this standard guide that is only for us internal specialists. Can you make sure that is always up to date as well? Then I only have to go to the configuration database and fill in the form with the customer specific configuration information – by hand.”

My reply to these guys has always been pretty simple, and the reaction has always been the same:

I say, “Sure, we can do that, and that customer specific configuration information… you don’t need to fill it in by hand. The system can do that for you. All you need to do is write your part in DITA XML.”

They reply, “That sounds great! But that DITA XML part… I don’t know. I know it’s really powerful, but I spent most of my day with customers, I don’t have the time to learn to write XML documentation.”

A few times we get to the point of agreeing that they should learn to write DITA XML… when we've had some breathing room. But we never get around to actually making it happen. Customers always come first for these guys – and they should!

Making the field agent NOT change

So, what if we can get rid of this DITA XML part for the field agent, but still be able to assemble everything into one deliverable sourced directly from the most recently approved standard documentation? Then automatically include the recent changes to the field agents' internal docs and be able fill in the customer specific content in at publication time?

We can do that. We can let the field agents write their content in MS Word like they have done all along.

Let’s take a look at an example.

Caroline Carrick is a field agent at Field Agent Inc. She works closely with customers.

When upgrading a customer to the most recent release, she needs a variety of documents and information available on the customer site.

Caroline needs:

• DITA XML sourced documentation created by the documentation department
• Field agent installation procedures
• Customer specific information
• Notes from previous visits with the customer

Until now this means that she will have to bring several documents and while working on the customer site, she will jump back and forth between documents.

This needs to change. Caroline wants to be able to get all her information in one place, where she needs it and when she needs it. But in order to get to that single source of customer specific truth, she wants to do her own writing in tools that she already knows – and so do her field agent colleagues.

Let’s take a look at where the information comes from when Caroline is upgrading a customer. In this example, the agents are using the standard product documentation for backup and recovery procedures. The documentation department is doing this in DITA XML.

The field agents have a shared process for installing the product. This is authored in MS Word. Inside this installation guide, there is a form that needs to be filled in with customer specific information and used during the installation process. This information is stored in a central database keeping track of customer configurations for all purposes in Field Agent Inc. In addition, the field agents keep a small log of tips, tricks and lessons learned with each customer, so they are captured for future upgrades with that customer. This is also written in MS Word.

Word Topics and DITA XML topics coming together

To make all these sources produce one deliverable that is easy to work with at the customer site, we need to take advantage of the DITA architecture. But that does not mean that field agents have to write DITA XML topics. Dx4 from DitaExchange allows a DITA map to combine topics written in both Word topics, so field agents can write in the tool they are most comfortable with, and in DITA XML, so we can get the standard product documentation directly from the source. And even inside the Word topics, we can leverage some of the powerful reuse mechanisms of DITA – such as content references, variables and filtering.

Going forward, Caroline will be publishing this map before going to a customer site and upgrading their system.

It is a DITA map that is edited in the user friendly map editor call DxNavigator. This map points to a few Word topics directly, and it uses two submaps.

The first topic is Carline’s internal notes about code of conduct at the customer site. This is just a regular Word file like any other Word file. She can open it and write in exactly the same way that her son does in the 7th grade.

After that she is using a submap. This is the standard backup and restore documentation written in DITA XML by the documentation department. Caroline does not need to worry about this content. Her map is just pointing to it, so she can be sure to get the most recent version every time she goes out to a customer.

After that is a similar map describing the field agent installation process, but this is a bit different in two ways:

• All the topics are Word topics, so the field agents can update them without having to learn DITA XML.
• One of the Word topics describes the installation process step by step. For most steps Caroline needs to configure the system with customer specific information like URLs etc. This topic is holding variable tags, so that Caroline can pick the appropriate customer when publishing the full deliverable, and the customer specific configuration information is populated automatically – directly from the database that stores the information.

And in the end Caroline’s colleague made some notes about the customer from the last upgrade that is worth making sure that she knows before entering the customer site.

Making life easier and deliverables better

So, in the end, there are two things that Caroline needs to do in order to achieve one single customer specific deliverable that is up to date and has all the information where she needs it, when she needs it:

• Write any new information in MS Word before publishing.
• Select the appropriate customer when publishing the document.

I am sure that most of my former colleagues would have been a lot more enthusiastic about reuse and automation at the thought of not having to learn to write XML content in order to leverage the power of DITA.

Oh, and by the way… the deliverable need not be a document. Even though she is writing in Word and mixing with DITA topics, Caroline can access the content in HTML on the company web portal. All her content can be fed into the internal chatbot, so she can access it out of installation context for trouble shooting purposes.