top of page

DCL Learning Series

Structure IS Freedom in Tech Docs: Understanding the Paradox

Marianne Calilhanna

Hello, and welcome to the DCL Learning Series. Today's lunch and learn conversation is titled “Structure IS Freedom in Tech Docs: Understanding the Paradox.” My name is Marianne Calilhanna and I'm the VP of Marketing here at Data Conversion Laboratory. Before we begin, I do want to share that this webinar is being recorded and will be available in the on-demand section of our website at And please submit questions at any time during this conversation; we will indeed save time at the end to answer your questions.

So I am delighted to introduce today's speakers. We have Mark Gross, President of Data Conversion Laboratory. Welcome, Mark. And Steve Wiseman, Product Evangelist at Paligo. Both of these gentlemen have spent their careers working with content and data structure, content management technology, and all the related services that help organizations support digital transformation. 

So when considering a move to structured content, some technical writers are concerned that enforcing content structure also means enforcing constructs that limit creativity and freedom in product documentation. But the truth is, structured content actually helps technical communicators improve the way content gets developed, managed, and presented. So, Steve, to get this conversation started and to make sure that we are all on the same page, I was wondering if you could please define content structure and structured authoring.


Steve Wiseman

First of all, thank you for inviting me. And you made me feel really old, because you said we've spent all of our careers doing this. No one's ever said to me before, I've spent my whole career doing something before. So thank you Marianne for making me feel 95. Probably the same for you Mark, I really appreciate that. Thank you very much.

The way I like to talk about the structured and non-structured and the rules and the paradox is, let's first think about a world with no structure. I'll give you two or three examples, although you only need one, but it's nice to give more examples. I was playing tennis this morning and yes, I won in three sets. It wasn't at Wimbledon. It was on our own local tennis club. Now imagine there were no rules of tennis. There were no lines. There were no nets. I'd never lose a game of tennis again in my life, but I'd also never win, right? It can bounce five times before you hit it. It can go into the pond and you can hit it back. No rules. That's example number one. You need some sort of ruling in order to play tennis. And no one says in tennis you can't be creative. Nice drop shot, or an under arm serve when the opponents aren’t expecting it. That's example number one.

Example number two, Marianne actually said, when we were speaking about this a couple of weeks ago. Imagine a road, imagine driving without any lines in the middle of the road. You couldn't drive; it would be dangerous. Imagine a government, living in a country without law and order. You'd be scared to leave your house. So the whole idea that having a structure or having rules is restrictive, I would argue the complete opposite. It actually gives you the base and the framework to be flexible and to be yourself.


You cannot work where there's no rules. Now I would agree with the other side of the equation, that rules can be too restrictive sometimes. And that's probably why people were interested by the title of this, because always, when people talk about rules, their assumption is always going to be there's too many of them. But that's not the case. 

A perfect system gives you the flexibility to have a really good game of tennis or to live your life in peace, and to walk out through the door and know you'll go and come back safely. So the idea of having structure is not a bad thing. It's just like everything else in life. I can drink, I can eat, I can exercise, but everything has its limits.


And we have to know what those limits are, and it tends to be a community idea, a communal of where those limits are. So that's just the first, the elephant in the room, of: structured is a good thing if it's done properly. Now to define what structured authoring is, let's define what non-structured authoring is. And I'll give you a couple of – I always find it's easier to do it that way, Mark. And I kind of use some very strong words about unstructured authoring, if you'll allow me, to maybe perk some interest. I call unstructured authoring, chaos, and anarchy.

And I think in a couple of minutes, you won't necessarily argue with me, even if you're working in those systems. Because everybody can create their own number of styles or classes, whether it's in HTML or Word. I don't want to mention other products here, it's not the point. I kind of make a joke, there are four things everyone does in unstructured authoring every day. They have breakfast, lunch, dinner, and tweaking. Because that's what you end up doing. You end up playing around a lot in order to get the content right.

One of my own statistics, and this has absolutely no statistical basis, no official research I've found for this, but every single time I speak to people they nod their heads, is that you spend 60% of the time writing and 40% of the time formatting. I spoke to someone literally an hour ago who said, "No, it's 50/50, not 60/40." Because you spend so much of your time doing things you shouldn't do. If you need to write technical documentation, you need to put an RFP out, you need to write a legal contract. You want to do that work. You don't want to have to spend the time fixing numbered lists or things jump to a different page or the image looks completely wrong or whatever those things that we're used to doing.

We don't want to spend time doing those things. We want to spend time actually doing what we're paid for, which is to create or curate. By the way someone gave me the word curate recently, because a lot of the time we don't actually write content, we kind of curate it from other people. So it's writing or curating content, that's what you should be doing, not playing with the formatting to make it, to make it look right. So where the structured world comes in is we have these kind of basic rules. Like, I can't put a title inside a table. There's only one way to put a paragraph under a list and et cetera, et cetera.

Simple rules that you would probably make for yourself. Work according to that list, have it validated when you save. And then when I marry it with a layout that I've made, whether it's for PDF or it's a printed document or it's an HTML site or a support platform, it comes out the way I wanted it to because it went according to those tennis rules or writing rules that I'd set up previously. Mark?

Mark Gross

Yeah. Actually, I want to go back to your initial point about rules in tennis and how it’s applicable.


I didn't think of that and I'm not the expert tennis player that you are, but the point is that your writing, certainly in technical writing, and much writing that happens, is to be able to communicate with other people. So following these structures makes it easier, makes it possible for other people to understand what you've put together. So I think the structure has become more and more important as organizations get larger, as you’re communicating with other groups.

When you're adding a specification, it's intended to be looked at by hundreds of thousands of people. An RFP is meant to be looked at certain ways. Fixing a piece of equipment needs a list of tools and all kinds of other things. So, that's all necessary. I think what gives the fear factor of, oh, it won't give me any creativity, is that you have to have the right amount of structure for that particular job. So, I think what gave it a bad rep is early methods of structuring were so tight that it was very difficult to work with those constraints.

I remember the earlier versions of SGML back in pre-history had rules that you spent a lot of time learning them and if you didn't follow them all, things didn't work. And not all of them were necessary. So I think as things developed, and that's why there's different versions of XML for different kinds of jobs and kinds of work, and you can adjust them so that certain things are necessary and not necessary.

So yes, a subtitle has to be inside a title, but maybe you don't always need a subtitle. So I think getting the right level of structuring for the job is probably what's necessary. But I think once you start working with them, it is very hard to say that – I mean, my grandkids talk about playing tennis without any rules, but it doesn't really work very well, because then they always win.  And that's not very satisfying either.

Steve Wiseman

And they won't win Wimbledon if they continue to play without rules.

Mark Gross

That's right.

Steve Wiseman

They could have a better forehand than Nadal, but it's not going to help them. Regarding what you said, Mark, I think there's a couple of things that scare people about the whole rules when it comes to authoring. One is, you're right,"Oh my goodness, will there be too many rules that I won't be able to do anything and it will restrict my work," which both of us have covered. But I think there's another thing as well. It has genuinely been really scary. And I'll use another one of my words, strong words, criminal, I think it's criminal. So in these long careers that you and I have had, Mark, that it's criminal, that it's been basically really hard to use structured authoring applications.

The cost, the jigsaw puzzles, the people involved, the maintenance of them, installation of them. There's a huge amount of work involved to do them. That's made it scary. Because everybody's involved, if you've got a team of 5 writers, 50 writers, 100 writers, one of the things you'll always need to consider is change management. And you might find a great app, but moving 100 writers still needs a lot of work. But if the app itself is going to be hard to use and the setup and the maintenance and everything goes around it, it's even scarier. So I think we've got two things that have made people scared. One is just not really understanding our structured authoring, maybe even just hearing the word “DITA” and taking two steps back and being scared of what everyone says about it.


And the app that you need, or the whole infrastructure, let's say, that you need behind it to actually get it to work in the first place.

Mark Gross

Right. And I think, today you've got pretty much out-of-the-box applications and schemas that could work. Part of it is, going back even 10 years ago, you had to customize so much stuff before you could get started, that the costs was – but today I think out-of-the-box is things that will work for most applications. So it becomes much easier to get going and that's also standardized and much less expensive to get started. So I think even if you looked at this 10 years ago and you walked away shaking your head, I think it's really very different now.

Steve Wiseman

Yeah. Maybe if you look at the history of CRMs, customer relationship management apps, if any of you guys remember them when they first came out. They weren't very easy to use. They were quite difficult and they were quite involved and even kind of saw a half database view at the beginning. And now, they've become so much easier to use. It's pressing buttons, setting up, doing integrations. And it's taken a long time, but, because I'm part of Paligo, which is a structured authoring solution, cloud based. And it really does take the pain out of it. Doesn't need to be so very difficult to be able to use structured authoring as you might have considered previously.

Marianne Calilhanna

And I think that's a good place to transition here, Steve, to talk about the easing the pain of workflow and tool changes. What are some of the benefits of consistency with structured content and ways you've seen organizations take away that pain?

Mark Gross

Just as an aside, not an aside, but just in terms of working with other people, other organizations, getting to that standardized point is very helpful, especially as you go to a global economy. And the example that I've seen a couple of times is container ships. I know container ships are in the news for the last few years, but the reason container ships came into being is because they became standardized very early in the game. And every container that you see on a ship is exactly the same, with the same kind of connections. And so the same cranes pick them up and put them on a ship and then put them on a rail car.

And so the advancement of a lot of this kind of technology is due to that kind of standardization. And we've got the same things going on over here in terms of the workflow and where you're getting things in and out. From a conversion point of view, a lot of what we get involved in is information is coming from outside sources and needs to go into a CRM in a particular way. And if they came from someplace standard, there's standard ways of being able to do that so people can communicate. I think that's just an important idea in terms of just the global workflow and I'll move it back to the specific workflows that authors would be getting involved with, Steve.

Steve Wiseman

It's really very much based on what we said before, because if I were to take two people, give them no instructions, and tell them to document, for example, how to, say, manage users in this application, or to write a page for an RFP or whatever document, or write a part of a contract, they will naturally not write the same content.


Unless they're Siamese twins, they're probably going to write in different ways. And what we want to be able to do is to have that element of consistency, and obviously again, not down to the nth degree, so it completely restricts them. For example, we're going to use something called a procedure element to put a procedure in and a list element just to put a list in and a bulleted list to put a bulleted list in. Simple rules like that, of how I'm going to do it. Or, if I'm going to put a table in, the basic formatting for a table, not has to always have two columns or three columns.

But we know when we put a table in, it's going to have these lines and these colors and these shading, and it's going to look in a consistent way. Or anything that I do in the documentation process. One, they're all going to be writing in a similar way. Also, the layout is going to be effective. I'll give another example, something called inline elements. 

By default, if you are writing instructions, you are going to, for example, from the View menu, click “Add,” right? So if you are, let's say in a non-structured environment, you'll put the View menu as bold and the Add button also is normal, bold.

You're kind of being restricted. What happens later? Let's say I want to make the menus to look green, and I want the buttons to look red. Or that may be a bad example, because it would look particularly ugly. And even though I'm really ridiculous with colors, but you know what I mean; one would be very bold, one a little bit bold. But you want these slightly different ones, you want to use some sort of more semantic logic of how they look to have that element of consistency through the whole document. Because otherwise everybody will do them differently.

So we have what's called inline elements that would define: the main menu should be called this and the sub menu or the button should be called that. And it's little things like that, just using the logical elements, by the way and element is like a style, but logical elements that will mean everybody's writing in a consistent way. Because, Mark, I'm sure a lot of the stuff that you get is that you are basically putting together, maybe, content from different sources and then putting out in one source for the company to continue using after that. And you can probably see all the different ways and inconsistencies that people do, to put it in one ruled and consistent way for them to work with afterwards.

Mark Gross

Yeah. And, just that brings up the point of, you're getting material coming from all kinds of different places and they might have different rules that were followed. So getting it to a consistent level is very important. But by doing this and being able to assign those kind of elements and how they're going to project means that you can also produce your materials for many different targets. No longer are we going to a printed book and that's the way it's going to be. You're delivering information, it's going to go on a large computer screen or it might be going on a phone or it might be going on a diagnostic device, which is looking different, different sizes, different things.

And each of these, you want to be able to, you want the elements to display in different ways so that you get the right effect. So a certain font will work very well on a large computer screen, but won't work well on that diagnostic device or on a phone or wherever people are going to be looking at it, or if you want to print out a few pages. So, the ability to assign different styles in different places gives you a lot of freedom later on to be able to use the same information in different ways. The other issue, especially when things are coming in in different ways,


and this is, when you’re working with – the scariest thing to me is – I mean, my daughter's an artist. She loves standing in front of an empty canvas and starting painting, which with me, that's terrifying. Where do you start? And people do things in different ways. And what happens is that, if the same idea and the same concept got pulled from some place, got pulled in different ways, then there are variations all over the place.

One of the things that we find very useful as you move into a system like this is to standardize, just not the way things are looking, but also the structures. The same idea may have been expressed in similar ways, across a whole bunch of places, we call that harmonization, so that you can use the same paragraph. Rather than rewriting over and over again, you can use it once and use it in many different places. But how do you find that? So one of the things we ended up doing in order to support this, because it was so necessary, is sort through, we’d go through a collection of documents, we call that Harmonizer, and find all the places where identical paragraphs are being used. Or even paragraphs that are not quite the same, they’re off by some punctuation or a couple of words here and there.

To be able to put them together so that the writer can go in and say, okay, this is the way I want to do it, and that's the way we're going to do it going forward. Because you want your creativity for where it counts, but the things that are low to routine, you probably don't want to spend a lot of time on that. So all those things are tools that ease the pain of moving towards this kind, in this kind of direction.

Steve Wiseman

Also notice the paragraph, Mark, like if I've written a procedure in one place, I'm confident I can use this somewhere else and it’ll behave in exactly the same way. A bulleted list, a table, a section inside a main topic, all of these, you need to have the confidence, because if you're going to reuse content and most of the time we’re reusing content, you said, between the different channels, the outputs could be between different documents, different products, different audiences, different versions, different, whatever.

There's umpteen, unlimited number of reuse cases everybody has and people are listening know their particular use cases. You need to have the confidence to know that I can reuse something in one place, I can use it in another. In the same way that I can buy a car in Liverpool, I know that I can drive it in London. I need to know I can write something for one document and I could reuse it with confidence somewhere else. And you only have that with structure. I wanted to bring another issue up though, just to make sure we don't forget, because I'm as prone to forget about this as anybody else, but we've got to make sure that we mustn't.

We're talking about the technical authoring, we're talking about the structure. Let's just remember why we're doing the content. We should always do in these types of discussions, we're doing it because our customers want to be able to read something or do something or answer a particular question or carry on with a business task. That's the reason why we're doing all this. I say there's three things that we should be involved in the all, the authoring experience, the collaboration experience and the end user customer experience.

All of those are really important and there's nothing more annoying for a customer to not rely on the content they're trying to find, that is organized in an inconsistent way. Or it's like for example, one person, one author wrote it in a very kind of informal way, they didn't use any type of lists. Another did it in a very procedural way. Another made it look like a contract. There's nothing more annoying for a customer to have that complete inconsistency. It's non-reliable.


They probably won't use the content anymore because they're just sick of trying to find what they want and when they find it doesn't really explain what they wanted to explain, or it's a different angle. You get used to everything you're reading. There's a habit you get into. So when I'm trying to read, say, DCL, I know what the kind of language is going to be. If I'm reading a Microsoft help page, I know what I'm going to get. If I'm reading an API description, I know what I'm going to get. But if I don't know what I'm going to get, I'm probably not going to go there in the first place, which will mean that I probably won't use the product properly. And I might churn from the product or service that I'm using. So let's just not forget the end user, the customer or the prospect, whatever they may be.

We must give them consistency. They must get reliability. Our patient levels are this big, maybe that big, they're not very big anyway. We jump from one thing to another. It's a habit. We need to put in front of our customers and prospects, what they need. And the most basic way to do that is consistency. And how do you get consistency? By an element of basic rules, in other words structured authoring, to get that content out in a way that will be reliable.

Mark Gross

Yeah. And I think one point also, if it's done inconsistently and the language isn't comfortable, you just don't trust it. So that becomes, I think, a big issue, in how the customer looks at it. But I think it comes back to the point that structured authoring done right makes it much easier to put things in the right places so that you don't have to worry about a lot of the details. I think that's the bottom line on some of this stuff. So the big issue at all times is getting into that structure in the first place so you can work with structured authoring.

That's what we do. So we've seen a lot of very unstructured material over time, especially when you're dealing with things that were written 20, 30, 40, 50 years ago. And believe it or not, there are systems that are still being operated. The B-52 bomber passed its 60th birthday a little while ago. So, things stay around for a long time and it's very important that there be a way of keeping that information around for a long time.

Marianne Calilhanna

Yeah. So let's shift to that conversation then, Mark. How does one get started with structure?

Mark Gross

So, I guess I jumped the gun a little bit over there, but I think what most people need to do as they're moving into a structured environment, a big piece of it is identifying the right tools to work with. And that's why Steve is here. One of the great tools out there that makes a lot of sense for a lot of different kinds of authoring. But getting all that material together, the first step is really figuring out what you have. Which is a little bit like digging around the basement sometimes and into the attic and which things are important and which things aren't. And a big piece of that is finding out what you really need.

So if you do have systems that are still operating after 50 years, then you need that material. But a lot of times that's not true in many areas. And the other thing is finding the best copy you have of things. And that involves a little bit of digging around. Do you have electronic copies? Do you have to go back to paper? That sometimes happens. Do you have PDF files? Do you actually have Word files or do you have other XML? So I think part of it is doing an inventory of what you have available and what the best possible formats you have are,


so you can put together a list of that and figure out what it's going to take to do. The other thing is phasing. You can't do it all at once. It's like boiling the ocean; it’s a tough thing to do. So I think what many successful companies have done is really phase what they're doing, identify a pilot project that they can start moving with very quickly, which will actually have visibility and people will see and recognize the importance. And I think Steve will agree, the material you're going to decide to do as a pilot needs to have somebody who's enthusiastic about it, involved at the company, who wants to make sure it works. The biggest issue I think we all face as we try to move things along into new areas is the fear of change.

And some people are proponents of change and they're really excited about moving there. And other people are very scared of that. So, the champions for this need to be people who are going to be proponents of that kind of change. And to make it easy to do. I think part of it is, I know that's self-serving, but getting expert resources involved in the pieces that most companies are not expert in so that the people that are there, that know the material, that are expert at what they are doing can focus on this hard job of moving towards a structured environment. 

Steve, how's that fit in with what you say?

Steve Wiseman

Yeah, next slide, Marianne, because Mark just said everything. I'm just joking. There's no surprising if we're on the same page together, we are agreeing with each other. A POC is always a good idea. I wouldn't necessarily do a POC that's huge and massive. You want to make sure they POC, they have a list of requirements, I want to do A, B, C, D, E, F, G, et cetera, et cetera. Some people have 10, some people have 200. Depends on the company, who's running the project. But you should have some sort of POC to make sure. You need a champion, like Mark clearly said.

You don't want someone who's running something who doesn't like change. But I'll be honest, anybody who is listening to this webinar, they wouldn't be listening if they don't like change. Because you don't listen to modern day webinars if you want to hear what people have been doing for the last 30 years. Obviously we talk about new things. So everybody here, is an assumption of mine, are willing to listen and to hear about changing things. And I was going to say on the previous slides, that every department works in a standard and structured way. Name me a department that everybody does what they want, where there's no inherent structure in their application.

There isn't one. Developers have the standards, sales have their methodologies and standards. So documentation and managing content should be in the same world. It shouldn't be out on its own sailing away in its own ocean without connecting to anything else. The people on that boat would've run out food and water quite quickly. So we really have to working in the same model as other people. But getting started with structure. The first thing actually might be this webinar. It's not as scary as you might think. Everything that Mark said before is just normal change management.

People, the migration process. But it's really not as difficult as you might have thought it was. I'll give a couple of words for those of you who understand the whole DITA world and the DocBook. Paligo, which is a company obviously where I come from, happen to use DocBook and I'm actually not going to explain to you the differences and why.


Do you know why? Because it's not very important. What's important is well, there's a structured authoring standard. Fine. What's really important is, does the application that you use or want to use fulfill the business objectives that you need for your content? That's the question: it's not “my mummy is better than your mummy.” “My standard is better than your standard.” It's not a question of that. It's “am I able to achieve my business objectives in the product I want to use?” That's the most important thing. Content strategy is what's the business application of my content? How can I organize my content in order to fulfill my business objectives?

Information architecture, by the way, is the, how am I technically going to go and implement that? So it's, can the tool do it? And if we do look in the past, and I touched on this before, it was very hard to do this type of thing. I was scared. If you'd asked me ten years ago, I'd have been happer carrying on working in Word than spending $500,000 in application that would still be $500 just to maintain it for the next 10 years. Because you now are able to get into a structured application. If I was starting from new, I would try that application. I would see how I can manage on my own. Can I really create conditions this easily? Can I do variables? Can I reuse content? How hard is branching? How hard is it for an author? Would it scare all my collaboration team, my reviewers and contributors, if they were to use this tool?

If I've got a new writer coming in straight from university next year, I've got ten new writers coming in the next three months, would these people be able to use a tool that I'm suggesting for them, or would it be really hard with all the XML tags and integrations and stuff that goes on? They're the things that I would be asking. And then I know we've got on the slide about migration, is how long would the migration be? How long till we can actually become efficient? Do I need to spend six months teaching my team to use a tool?

Or could I do a few hours of training and some homework and get them together? How quickly could I make a style guide or a playbook, which is a more modern word for a style guide, of how to use the system environment? So how quickly can I get going? And if the answers to these questions are potentially surprisingly quick, relative to what they have been in the past, wouldn't you go in that direction?

Mark Gross

That's very dramatic, wow, you're into that. I think it's excellent. And, Steven and Paligo have done a number of proof of concepts, POCs, with various customers and it does need that try it and see how it works, makes a huge difference. The critical difference. And there's always questions. Everybody's material is different. Can it handle these kind of equations? Can it handle this chemistry? Can it handle this or that? And so those questions have to be answered and that's the kind of things that get done in a POC.

So, again, it's not quite a do-it-yourself kind of thing yet, it's not just plug-and-play like today, much stuff I get has no instruction mailing or whatsoever. You just push it and it's supposed to work. There's a little bit of that, but it's certainly not what it used to be. And a POC really does answer a lot of those questions very quickly, I think very effectively. I think that's been our experience, certainly. And ending with that. And there are things to consider, besides just the structuring itself.


There are other things that make sense as you're moving along in this direction, and just going along. How do you start with this? Besides getting the structure, the next step would be something that can control the vocabulary. So that can be done at this time and there are tools that lets you make sure that you are always referring to things in the same way, instead of referring to a particular part in 14 different ways in 14 different places. 

So once you've got into this kind of structured area, you can go towards a controlled vocabulary. You can go towards – the camera just slipped by, sorry. You can go towards making sure that all your metadata, all your information about a paragraph is in the right place. This particular paragraph, when is it used? When is it not used? This is a tool. All those kind of information to be pulled once you get towards structure. So there's a lot more than just meets the eye as you move towards that kind of structure.

Steve Wiseman

And don't forget about taxonomies, another word that's used in enterprise at the moment. Taxonomies and ontologies, for those of you who are not familiar. There's a couple of words that I find people get scared with: the components and taxonomies. So with components we're not talking about now, but at least we'll deal with taxonomies. Those of you are not familiar, but it's actually a term being used much more in organizations and enterprise as a whole, where they want to categorize content across the whole company. The most inefficient part of any company, I would argue, is the management of content. Across the whole company, your sales, marketing, human resources, just all the departments in your company.

People write the same thing a hundred times. Ideally, a company wants to be able to find a single source of content around the whole company. And one of the ways of doing that, one is structured authoring, because if it's easy enough to use, everybody can use it. So you have the single source of authored and published truth. And the metadata or the taxonomies or labels. Metadata, if you imagine Gmail where you can label things or whatever application you're using, that's what taxonomies are. And so you can organize your content. You can organize your content by folders and product. You can have taxonomies by country, by version, by market, by operating system, whatever you want. It will give you many more angles to get to your content.

In terms of the end user experience, let your customers do a filtered search, a faceted search to drill down to the content that they want. Allow other people in other parts of the organization to find content that you've written. And taxonomies are such a huge part of that. Now ontology, I call them 3D taxonomy. It's how the taxonomies, different ones, all fit together. That should also be part of this type of solution if you can, because again, people can find the content they're looking for from all different parts of the enterprise.

Mark Gross

And these are a lot of fancy words that are not very complicated concepts once you really start looking at them, but you don't have to do it all at once. I think, sometimes you do, but sometimes you just want to get going and get into a structured environment and you can add those other pieces on as you're going along. Because once you've put things together, you can now start looking at it more easily and pull them together. So there's different ways of doing this depending on how you want to go and what you need to do. And how do you phase it in so that you can show results early and be able to get buy-in as you're going along.

Steve Wiseman

Very, very good advice from Mark's long career. But I would agree with you. I would agree with you entirely.


Sometimes you need to do the whole thing at once, but sometimes you can do it piecemeal and learn as you go along. It depends on the organization. If you've got 100 writers and you all want to use the same product at the same time, then you probably have to do a small POC than a big change management job. In other companies, maybe we'll start with this product, see how that goes, and if it works well, then we'll bring it into the whole company or the whole department.

Mark Gross

Okay. I think we’re… Marianne, were there questions that you wanted to bring in here?

Marianne Calilhanna

Yes, we do have some questions, so we can shift into that; we can shift into opening up to everyone here. If you'd like to add some more questions, just use the dialogue box on the GoToWebinar panel and feel free to ask anything. Steve, you mentioned something, and someone quickly typed, you mentioned branching, and can you explain a little bit more what branching is?

Steve Wiseman

Well, that's a good question. Tempted to share my screen, but I'll try to do it without sharing my screen.

Mark Gross

Waving their hands.

Steve Wiseman

Yes, I'll do that. I'll try and be dramatic again, Mark. In the old way of working, it was very simple. You basically wrote something and six months later or a couple of months later, you produced it, it was finished. And then you need to make another version and be like save as the Word document and create another one and it all worked in nice, timely, non-complicated orders. Then unfortunately, Agile came along with this multiple steps, little steps all the time, going up and up and up and up. And that's made life a little bit more difficult for everybody, not just content people, because you often now need to have versions working in parallel to each other.

So for example, I might be writing in version 1; that needs to stay live while I'm writing for version 1.2, which will be out in a month. And maybe I need to write my new stuff for 1.2, still doing bug fixes, also in the docs for version 1. I've got both of those in parallel and maybe later I need to merge the two together. So like Paligo, it's a cloud based product, we don't have multiple versions, so we'll push them back into that same document version. Just like the product's the same version. That's branching where I branch from my 1.2. I branch from my second version. And then later when I'm ready, if I want to, I will merge it back into the source and that'll be my live version. Just by the way, a couple of things difference between devs and content branching.

A lot of you might be using things like Git for branching or GitHub or the like for it, for your documentation. I've got an expression. You kind of know me by now, I have a lot of expressions. I'll keep out of your kitchen, if you keep out of mine. And it's not just my wife, we've only got one kitchen, telling me that. It's more like, if I was going to a developer and say Mr. or Mrs. Developer, or Ms. Developer, I want you to do all your coding and all your branching inside Paligo, which is a content management system, they would say, Steve, you're completely barmy, you're completely mad. Get out of here. So in the same way, why should documentation people be using versioning systems for developers?


It's the same missed paradigm. So if we're talking about branching, whatever system you're using, you really should be using branching where they talk about your content, making versions of publications and versions of topics, making versions of admonitions, excuse me, like notes or tips or whatever. But the simple answer, Marianne, to your question that I probably went on for too long,


is that branching is a way to manage multiple versions of your content. It can both be for internal and maybe you also have external versions. You have multiple versions of your content live in the market. They're also a kind of branch, different, for your customers to see. That's what branching is.

Marianne Calilhanna

All right. Good answer. Another question that came in, do I have to use DITA? I think that word scares people sometimes.

Steve Wiseman

So, you know, like this – Mark, do you want to take this one? Can I take this one?

Mark Gross

You can take that one. There's lots of ways, different structures. There are ways and things without being scary and I just relate to, it's also different kinds of material might be different kind of structuring. But I think, Steve, you probably should handle that.

Steve Wiseman

So, you know, like, at least in England, we use the word “Hoover” when we mean a vacuum cleaner. We say, you're going to go and “Google” when you mean to search. There's a word for it and I've forgotten what it is. If someone knows, put it in one of the questions. There is a word and I've forgotten what the word is, when a product name becomes the actual name of the functionality. So structured authoring is really what it is. DITA is one of the standards. It just happens to be the most famous standard. It happens to be one of the complicated standards, that's why Paligo didn't choose it.

But it's a standard like others. You actually need to learn a lot more when using DITA because it's got so much in. Not saying anything negative about it, but everybody would, I think, probably agree, it's not an easy standard. You need to learn the theory before you learn the practice. You need to learn about DITA before you learn the product. So the important thing is just remember DITA is a standard within structured authoring.

The airline industry has its own standard. There's DocBook and DITA for regular tech docs and regular documentation. So first thing is no, not everything is DITA. First, just learn the structured authoring. And the same thing I said before, when it comes to an application, choose an application that solves your business needs. Don't go "I need DITA." DITA just doesn't mean anything in terms of the business requirements. You might need DITA, you might not, or most likely, it really doesn't matter.

Mark Gross

Right. No, I agree. A lot of times it really doesn't matter. We're dealing with technical documentation; there's a few different ways to go. We talked about DocBook, we talked about DITA and there's others also. But, it really doesn't matter, as long as it's fitting that application. In the scientific publishing community, there are other standards like JATS, and in the standards field, there's different things. So I think it's critical to get the right tools for the job and it all starts with what are the requirements in the work you're doing to make sure that it fits. And if it fits close enough, then there's some tailoring that can be done to make it fit even closer.

Steve Wiseman

It's like I said before, Mark, it's not “my mummy is better than your mummy.” It's not “my standard's better than your standard.” It's “how do I achieve my business objectives with the content?” That's what it's all about.

Mark Gross

Exactly right. You’re right.

Marianne Calilhanna

So, we have two responses, Steve. That term is “genericide.” And I've also heard of “proprietary eponym.” I think I pronounced that properly. So yeah, I always hear “Kleenex” rather than “tissue”...

Mark Gross

It's also called an IP lawsuit, but…


Steve Wiseman

Not for us, hopefully, today, Mark.

Mark Gross

Not for us, no. No, my son's an IP lawyer, so I always lose those battles with him.


Steve Wiseman

Mark, we've actually learned a lot about you today. We know you've got kids that play tennis. One of your kids is an artist. And you've got an IP lawyer as a son. That's a very talented family. At least I'm listening.


Marianne Calilhanna

So here's another question. I think we've sort of talked about it a bit along the way, but it would be good to just review. “How do you go about doing a good migration to a structured environment? I have all types of documents, PDF, Word, InDesign. I don't even know where to begin.”

Mark Gross

So, we sort of started talking about that, but I think it still comes down to doing an inventory of what you have. First of all, an inventory of what it is that you need and inventory of what you have. And each of the formats you described, there are good ways to be able to move that information and add structure. The problem with all those formats that you mentioned is that structure's not built into any of those. So some structure, structure has to be built in or inferred, which is what we do when we do a conversion project.

We work with a customer to figure out different samples of material, how would you like to structure this? What does this mean? What is the best way to pull this together? And then put together an automated process to be able to pull those things in and make them all fit into the structure that we're going into, whether it's DocBook or DITA or whatever format we're using. Now, because it wasn't meant to be structured in the first place, there's things that fall in naturally and other things that won't.

So there's usually some level of preparation that needs to be done or those things just don't fit the flow. What did you mean over here? Is it supposed to be part of this section or is it part of this section? What do you mean by this kind of vocabulary? So there's a combination. So what happens up front is reviewing inventorying it, reviewing the material, putting in a specification of how you would do the conversion, and then it's a production process.

But it all starts with what Steve said, you've got to make sure that you're going towards where the customer – with your end goal in mind. So knowing what the end goal is is really part of that whole analysis phase that happens. If that gets done smoothly, then I think the whole project gets done smoothly, and you have a great system once it's up and running. And I think part of that, in parallel to all that analysis, that proof of concept, to make sure that people see what it really looks like. Not just in theory, but to actually play with it, work with it, see how the system works and be able to tweak the process to make sure that it's designed correctly before you move forward with doing everything. Steve, over to you.

Steve Wiseman

Surprisingly, I've got a little bit to add on that, but I agree with everything that you just said. There's a couple of things. So first of all, the question itself is basically, how do I bring all those unstructured solutions into a structured solution? All those examples you gave, such as Word or unstructured frame, InDesign, the like, et cetera, et cetera.


And I often explain these to Paligo customers that it might be painless, or it might be painful. We have no idea. We have imports, we have DCL. It depends how organized that content is. And you just don't know when you're coming from unstructured. It could be very nice, but every document's done completely differently. And that affects the amount of time and the effort to import that content. On the other side, I also give advice, which is similar to what Mark said a little bit, you need to know exactly where you are going before you import a single piece of content. So say we're in Paligo or whatever application it is, I need to know what's my reuse policy, what's my branching policy, which elements am I going to use, how will I do conditions, how will I do variables?

Have a collection, maybe just a few topics of example content covering everything you would possibly do. Then, once you've got that, then you can go to Mark and say, okay, this is, this is my end game. This is how I want it to look, please import. Now what I might be saying, you might say Steven, that's ridiculously obvious. You're wasting our time on this webinar telling such obvious comments, but you know how many people don't do that? People basically, they import and guess, and then they reorganize. You have to know. If we use tennis, like we used 55 minutes ago, as an example, if I don't know where I'm going to hit the ball, it's not going to get there.

You need to know where you're going if you're going to succeed. Maybe it'll work one in a hundred as a fluke, as a piece of luck, but that's no way to build anything or win a tennis game. You need to make sure you know where you're going, clearly, before you start importing potentially thousands and thousands of pieces of content. Otherwise you are going to spend a huge amount of wasted time. Any solution is 50/50, it's 50% product and 50% brain of human beings. And the brains of human beings need to do their part for the systematic side. So whether it's Paligo, whether it's Harmonizer, whether it's the conversion process. But the human side needs to do its part as well.

Mark Gross

Absolutely. Absolutely. Although I would say that very often, you don't know exactly what it's going to look like, the other side, so I think some of that proof of concept is intended to clarify things so that you can have a clearer idea. Because otherwise it could be very overwhelming. You look out, they say, oh, I'm not sure exactly what it's going to look like at the other side. But building that model first and making sure it's right helps clarify that in people's minds. And our process actually has several points in it where people can look at it and say, oh yeah, that's still what I mean, that's still what I mean, it still looks right. Okay.

Steve Wiseman

Yeah. Mark, every product is overwhelming. Whether you're building a new piece of software, whether you're an architect building a house or building a 30-story building. Every single project has multiple points. Exactly what you say, you build them into smaller parts of the project, you have milestones along the way. Everything big is scary until you organize and break it down into its constituent parts.

Mark Gross

Yep. That's absolutely right.

Marianne Calilhanna

Okay. We have one final question, let's see if we can answer this. Are there any good examples of POCs for structured authoring?

Steve Wiseman

Good examples of POCs? I'm not sure how to answer that question. I think it's any examples of content that's being created. An example of a good POC, and this is what we tell people as well, if we're going to talk about projects, create two lists. First of all, create a list of the five most important things you want from a solution that you'll be able to check later.


Maybe easy to use, lots of reuse, whatever they could be. But then also make a longer list of your requirements. So you probably then have a 50 list of the more detailed ones. It includes variables, I can do this, I can do that. And maybe the third part would be to have, import some content of yours, even at a basic level, without doing a full customized import to make sure that A, it is possible to get a content into this system. And B, I can create some sort of layout even out of the box that goes some direction to matching what I need.

Mark Gross

Right. And I think just going back to what we were saying before, when creating a proof of concept is, first of all, do it someplace where somebody's a champion, in a group that's going to champion it. And I think what you just said, it should have examples of all the kinds of things that you want to be doing so that you can verify that at least most of them can happen out of the box and get some reasonable confidence that there other things can be done once it's been tuned to your specific requirements. But it goes on; each organization looks at its content in different ways, so I think it's, what will convince you that this is going to work? What will convince your boss? What will convince that committee that this is going to work, is an important part of it.

Marianne Calilhanna

Right. Well, we are just about at the top of the hour. Thank you both so much for sharing your thoughts and your insight from your long careers. In no way is that intended to be an insult, Steve. It's more an admiring note for what you've invested in this topic, in structured content and structured authoring.

I want to thank everyone who took time out of their day to join us. And I'd like to just remind everyone that the DCL Learning Series comprises webinars such as this, a monthly newsletter, as well as our blog. You can access many other webinars related to content structure, content reuse, XML, from the on-demand section of our website at I hope to see you at future webinars. And wherever you are, have a great day, a great evening. And thank you so much.

Mark Gross

Okay. Thank you, Steve. Thank you, Marianne.

Marianne Calilhanna

And I'm just going to end putting Steve's email address out to anyone if you'd like to connect or ask him any questions personally. Thank you.

Steve Wiseman

Looking forward.

Marianne Calilhanna

This concludes today's webinar.

Steve Wiseman

Bye, everybody.

bottom of page