Cruce Saunders
Welcome to towards a smarter world I'm your host, Cruce Saunders, and today's episode is part of our series looking at content leaders and the composable revolution. We're fortunate today to learn from Mike Hedblom from the technical documentation community and we're going to discover how tech doc teams work with structured content and look at how that relates in some ways to the marketing side of the house as well. Mike is the Senior Director of Documentation at Medallia. A leader in experience management software. He has over 35 years of experience in the software industry, covering a lot of territory and change, both with writing and leading international teams, developing online documentation solutions. Mike lives in the Silicon Valley and has worked for a number of different industry leading companies and startups. Welcome, Mike. Thanks for being here.
Mike Hedblom
Thank you. Glad to be here.
Cruce Saunders
Well, I hear you've got an interesting modular content project going on now, and that you're responsible for really that whole content supply chain that generates personalized content. So that means you're driving the customer iterations and the content components that are assembled based on the audiences that interact with it and access that content. So you're dealing with content assemblies. Can you tell us a little bit more about that project?
Mike Hedblom
Sure. What we're talking about is, in this case, the product documentation for our various products. Medallia has a number of products. Each of them has varying degrees of software documentation. In addition to having different audiences of developers and administrators and users, we also had a need to have content that is internal for Medallia only to see. And we had content that we didn't want out on the public website. We wanted it to be able to access through a login so that certain customers can only see information once they've logged in. So that was the solution that we were trying to achieve. We finally are doing now we're doing all that with Heretto's CMS and Heretto's deploy portal software.
Cruce Saunders
So can you tell me where did the project begin? What was the seed that really initially moved everybody towards modular content? Sounds like these three different audiences, each needing to have access to different versions of the content, was one of the seeds. Were there any others?
Mike Hedblom
Yes. There's a number of things that got us going on this project. Stepping back. When we first created the Medallia product documentation, we decided to go with DITA. It was about eight, nine years ago as a format because it allowed us such flexibility. Some of the beauties of using DITA content is that it's very modular, very semantically organized. And in addition to that, you can tag the content with various attributes @mikehedblom One of the attributes you can say "for this piece of content, what is the audience?". In our case, we define an audience as public, private, or internal. So in the content itself, we've already flagged who can see this piece of information. And we went with DITA for a number of reasons. One of them primarily at the time, was we wanted to be able to reuse content. So we have lots of cases where there is something that is said in one place and we need to say the same exact thing in another place. Traditionally, you might copy and paste that, and over time, somebody else comes along and takes one of those things and makes a change to it. So now you've got divergence between the content with DITA, it allows you to actually use one piece of content and have it appear wherever you need it to appear multiple times.
Some of the beauties of using DITA content is that it's very modular, very semantically organized. And in addition to that, you can tag the content with various attributes @mikehedblom
And that was really important to us because we had a lot of reference material where there was a lot of duplicate information. We wanted to be able to say that once. Part of the advantage of that saying it just once is that if you localize the content, translate it, you only have to translate it once instead of ten or 20 times or 40 or even 100 times across multiple different pages of documentation @mikehedblom Instead, you're just translating the source one time. So that got us going in that direction initially, why we went with DITA. Eventually our current solution allowed us to publish pages of content, pages of documentation using those attributes I was talking about, those tagged attributes to say that "only show this content to an internal user", or "only show this content to an authorized restricted user", one of our customers. And that's the solution that we have now. We have a single website for our product documentation, same URLs, everything, but different people might see different content on that same URL based on what we know about them. And that was key for us. That's the big advantage to us. We can show internal notes or instructions to employees that do not appear when the user page or a customer page, but the same page when an employee looks at will see the instructions on what they need to do.
if you localize the content, translate it, you only have to translate it once instead of ten or 20 times or 40 or even 100 times across multiple different pages of documentation @mikehedblom
Cruce Saunders
Okay, so your team started out with a content architectural approach, building with a public content model in DITA. Can you tell us a little bit more about for the folks that don't know what DITA is, (Darwin Information Typing Architecture). What is it and why did you end up deciding that DITA was the best architecture to move with?
Mike Hedblom
DITA itself gives us the greatest flexibility in terms of being able to put documentation together. It allows us to have pieces and assemble them at the time we want to publish them, so we don't have to have long documents of content. We can have an overview. We can have a separate piece that's a reference. We might have tasks. The DITA architecture really is a way of classifying content, semanticly identifying it. And there are people who are very evangelical about how to use DITA. And you say this is a piece of overview, content or concept, this is a task and this is a reference and you use all those features. And when you use those classifications there is again semantical information that's specific to that type of content. If I have a task element, for example, a task is going to have steps in it. And so when you're working with the content you say here's a step and here's a sub-step and there's information about the step. So it's a way of classifying each of those pieces of content. If you at all familiar with HTML, or just even simply if I'm looking at a document of text, I'm just looking at it, I might see a paragraph, I could see bold text, I might see italic text, I could see headings.
Each of those things is a semantic element in DITA. What's nice though about what we use with Heretto is that's all obfuscated, it's all hidden behind the scenes. I get to use a simple GUI editor just like you would see with Word or with Google Docs or something like that. And I edit my content and I just write it and it looks like a printed page, like a WYSIWYG page, but behind the scenes it's all tagged, has the semantic information behind it that allows us to then assemble and reassemble it and do things with it that you can't do with other with Word documents or Google Docs type of thing.
Cruce Saunders
So it's enabling automation, translation, analysis, transformation, lots of different actions that you can take with these content modules. So these different chunks, these topics that are reusable in different ways than documents and that is something that lends itself to these scenarios that you're talking about, where content needs to be targeted to public private customer use and internal employee use.
Mike Hedblom
We don't do it, but a lot of companies use DITA. Even beyond that, we're just focused on product documentation. But if you follow the DITA model and you follow content modeling, you can use the same content for your training material, you can use it for your marketing material, for your sales material and that way you've got a single source of truth for all the content that you produce in your company. We don't use that model, but it's a very common model and I've seen people do it and it's really impressive. It's nice to be able to say what a particular feature is and have a description of it and be able to use that same description across the corporation @mikehedblom
It's nice to be able to say what a particular feature is and have a description of it and be able to use that same description across the corporation @mikehedblom
Cruce Saunders
Yes. We work with a number of clients who are doing cross departmental content reuse between presales content and post sales content so that there can be a continuous customer experience. For example, using the same semantics to tag up different content chunks that are related to the same product. Customer intent. Like the thing that the customer wants to do with that part of the product. Some of that might be marketing material and some of that might be support material, but it all has to be assembled based on what the customer's context is. And so in those cases we've built content models that incorporate DITA but might also have other logical structures that meet the needs of a particular marketing funnel. It starts to get into more content orchestration at that point. But it's like DITA is an excellent foundational piece that can be used out of the box. And it sounds like you really have gotten a lot of value from using DITA and its native structures without needing to specialize it or extend it too much. Is that right?
Mike Hedblom
Yes. In fact, DITA has what they call a topic. Everything is a topic. And then they have specializations that I mentioned, concepts and tasks and references. By default they have other specializations as well. We don't use those in our company. We just use everything as a topic. We didn't want to get into customizing the existing stuff, we just wanted to keep it real simple. Can we just use what DITA provides us out of the box? And so almost everything we do is a topic. So we've actually begun to look at using tasks and we've started using the task things because it came out real nice for some of the things we wanted to achieve for some of the more task based topics that we have. But we completely avoided the specializations, customizing it ourselves and that made understanding how to use it much simpler. You just have to learn a few simple things.
Cruce Saunders
No, I love that it's a very practical way to get started with structured content to demonstrate value very quickly and accomplish some really clear business goals. Right. We got to get content to multiple audiences.We don't want to rewrite it on a bunch of different pages. So what's the most efficient way to do that? @mrcruce And it turns out you found in real life DITA is working for you to do that. I wanted to talk a little bit about the tagging because you mentioned that you had flagged content based on who can see it and so you those tagged attributes on the individual topics, is that right?
We got to get content to multiple audiences.We don't want to rewrite it on a bunch of different pages. So what's the most efficient way to do that? @mrcruce
Mike Hedblom
We take it down to a very small granular level actually we can tag a topic. We can tag an entire section we'll call a "map" of all the topics within a group, like a collection. We can say that they all get the same tag, but we can take it down to a very granular level. In some of our release notes, we tag a bold attributes on the bold in some of our content. So only the internal audience sees something as bold. The customer does not see something as bold. In fact, they don't even see that content. The flexibility is amazing what we can do with it. We can take it from the very highest level. An entire section of the website is blocked out down to can I see this old text or not? The power was just wonderful in that regard, it gives so much flexibility.
Cruce Saunders
Is there other kinds of attributes you've extended beyond the permission attributes? So other kinds of metadata that you're attributing to these different components?
Mike Hedblom
Not really. At the moment I would like to be able to go further with it and that's kind of my next version of it is to be able to have this is administration documentation, administrator document, this is developer documentation, this is end user documentation and to be able to tag that. And I would like to be able to have on the doc portal the ability to maybe say, just show me the developer content. I don't want to see this stuff or hide developer content from end users because it's just not worth it to show them that content. That's my vision for the future is to be able to do that as well. So we're not doing that yet. I think we're going to get there eventually. We do use other attributes, but nothing else meta that really surfaces through like that.
Cruce Saunders
Okay, yeah, we see some organizations that have metadata profiles that are way bigger than the content itself. There's some organizations that just go nuts with metadata, but it sounds like your general strategy is sort of minimally viable metadata.
Mike Hedblom
Yes, we really do focus on keep it simple. We've started to look at a number of times, should we classify content so that we know if this piece of content, this topic is related to reporting. So we maybe say this is a reporting tag. Or these are things that help you when you need to understand reporting, or these are things that help you with account administration. And every time we start to look at that, we end up backing off because we don't really see how we want to apply it. And that's always the goal for us is what is it we want to do with this information and will we actually use it? We could spend a lot of time going through tagging things with a taxonomy, but if we never use it, why bother, right?
Cruce Saunders
Yeah. If metadata was in a forest and nobody actually used it, did it make a sound, right or whatever? There's a real interesting thing that happens in content architecture and planning engagements where we start creating for all the things that content could do in the future @mrcruce And it sounds like your general ship first approach is get it out there working and then incrementally improve it. As the universe says, this is necessary.
There's a real interesting thing that happens in content architecture and planning engagements where we start creating for all the things that content could do in the future @mrcruce
Mike Hedblom
I've always told my staff and teams that I've worked on, I used to call Mike's Rules of Software. And rule number one was you've got to ship version one if you ever want to get to version two. So many people spend so much time perfecting the first thing that they never get a chance to fix it and see what works and doesn't work out. Here in Silicon Valley, there's a lot of move fast and break things or fail fast, that type of thing. I don't want to fail, but we're going to fail. But we want to learn from it and let's take what we've got, learn, see what works and doesn't work and how can we improve it. It may come back to bite me someday that we didn't spend more time on a taxonomy and, oh, now we've got to go back and recategorize and tag things. But for now I've got a small team and we don't have time for that. We need to ship content. We need to get it out there, and this is the system that allows us to do that.
Cruce Saunders
Yeah, and there's probably some rule of Silicon Valley that I haven't heard published yet where if you wait long enough, AI's will eventually do it anyway.
Mike Hedblom
Where's the AI get its content. That's what I always wonder. It's got to get it from somewhere. If you have a new software feature, where's the AI going to learn about that feature so that it can tell you about it? So we're still going to have content producers.
Cruce Saunders
Well, let's talk about the content producers. Actually, I'm really curious about what that has looked like for them when you move to DITA. I mean, that's been a while now, but what advantages do they see? I mean, a lot of authors, if they come from an unstructured background, they're used to just working in Word and so using DITA, there is a behavior change that you're making. You're using structured content of any kind. There's a behavior change because you're templatizing content so that modular writing can be new for folks that aren't trained tech docs from birth right, a lot of folks come into writing documentation that don't necessarily have that formalized background. So I'm curious about how that process worked with your team and what some of the challenges are that they faced, and how it's gone.
Mike Hedblom
It goes back to why we originally chose Heretto. I really wanted writers to be able to work, authors to be able to work without having to understand the underlying source. And what I mean by that is, I didn't want them having to go into source code and write and see tags and understand the various things. I really wanted that hidden. I wanted them to just focus on writing. And so having a WYSIWYG interface where I can just write and see things and not have to understand the underlying structure was so important. I can sit anybody down who has ever worked with Google Doc or Word and I can have them write content and they can produce content very simply and easily with Heretto you already know how to do bold and italic there's little menu icons you can click on for that and it makes it bold. You see the italic and you want to lay out a table? Fine, here's a table. All that stuff is there. So they don't have to understand DITA behind the scenes and structured content in general. I'll just say, so just write the stuff out. Then we'll start working on how to tag it, how to do these things with it.
We tend to write longer topics instead of short modular chunks. There's a theory of some people should write just a small chunk of topics and a chunk of that and that way you can pull them all together and reuse them. And we tend to write longer articles in part because that's what our audiences' like. But the learning is not that hard for somebody bringing them in. I can teach them the basics in an afternoon. The people that I actually have the harder time with are the people who are pretty technically savvy and understand what's going on in the background because they want to get into the source code and see it and change it and do it the way they want it. They want to format the source code the way they want to see it indented. And it's like, oh my gosh, I want to take that source code editor away from them. It's just right, I hired it. Right? It's kind of funny because you do see that people have opinions on how things should be structured in a structured document. And if you can hide that from them and just say, I've got some content, here's a paragraph, I'm going to start a section now and the section has a title and things like that. That's a much easier person to work with than somebody sometimes who's got a lot more experience.
Cruce Saunders
Yeah, the intuition is such a key thing. It sounds like this is an intuitive solution for editing DITA that lets people write and edit DITA topics without ever learning XML. So they don't have to be DITA experts, they don't have to look at code even. And I feel like that's really a good lesson for all of those folks working in structured and modular content platforms across the board is to move closer and closer to this intuitive WYSIWYG ideal and still capture semantically enriched structure. And that's always the interesting line to walk down is how do you get just enough structure and capture it in an intuitive way so you stay out of the author's way, make it as smooth, as easy as possible, but also have enough componentization for the machines to be able to work with behind the scenes.
Mike Hedblom
Right? That's where if we were a stronger DITA house, I might have to spend more time with them. Okay, are you going to create a concept now or are you going to create a task? So let me explain the difference between the two of those things. I don't have to do that. I can say you just go to this menu and say, I want to create a topic now. Here you start writing, give it a title and start typing away. Having that semantic content really does give us a lot of flexibility. There are things that the more seasoned, the more experienced of my staff who really know how to use this stuff. They can do some pretty amazing things. I'm often impressed by, wow, how'd you do that. We have content where the same pages basically appear in two different manuals in the same project. On one project we have to call it Product A, and the other we have to call it Product B. So these are variables that we can set up in the project, and the system just says, okay, in this project I'm using variable A, and this one, I'm using variable B.
Even though it's the same source page that we've got, we're just publishing it differently as if it's in two different pages. That's the type of complexity of things you can do with it. Pretty cool when you get into it, but you don't have to know that. And that's the nice thing about it. For me, as an architect manager of the system, I can decide how far I need somebody to go and I can work with them on it. But for the most part, my team is just producing content and they don't ever really have to get into that. I've only got a small subset of the team that really kind of gets into that and says, wow, I can do these cool things with it.
Cruce Saunders
Yeah, no, that's great. So walking that balance is something you've been able to successfully mediate so far. I'm curious about the way content is being presented. So once content is inside of your system, inside of Heretto, it's structured, it's modular, and then it gets presented out to your documentation portal. So I'm curious about that system architecture from the listeners in our audience that are focused on the marketing side of the house. There's a big movement towards API delivered content. This kind of the composable revolution where we're delivering content-as-a-service via these APIs that allow for content to be queried and then presented in many, many different formats and ways. I'm kind of curious about how that is working coming out of Heretto and how your tech docs portal actually comes together and how much you work on the presentation side.
Mike Hedblom
Sure, sure. There's the underlying CMS, the content management system, which is the Heretto provides where all of the data and content are stored. And we never see that database. It's all behind the scenes, but all of our DITA content is stored in a database. And when we go to use the editor, the editor itself, it knows how to go ask the database, give me this content. And as I'm typing new content in, it says, here's some new content for the database. The CMS. Again, my team doesn't know anything about the fact it's a database behind it. They just write in the editor. It's a similar thing for the presentation. There's an application framework that we use, called Heretto portal. Which knows how to query the database for content, for pages to be rendered as HTML. So when somebody says, I want to see the page on this product, I click a link, that Heretto portal goes to the database, requests the content, it's properly filtered based on the APIs, and it's delivered to the Heretto portal software, which then renders it into HTML and sends it to the client browser. So the separation there of the web application from the source content.
Traditionally what we would do is we would go through that source content and build out static HTML pages and then deliver those HTML pages and say here's our documentation. What this system allows us to do is to actually query the database at the time the page is requested and build the page that way so that we can change content anytime and get the most recent content. And you're not having to deal with these static web pages that are suddenly out of date. The nice thing about that though, is you could use other systems to do something similar. Other systems could also be hitting those APIs and requesting data, and only authorized content would be delivered through those APIs. It's a really interesting way to deliver content instead of publishing it's like printing a manual, printing a book, instead of going out and printing the book and saying here you are, it's done. Oh, now it's out of date already. It's more like I turn the page and it goes out to the publishing system and pulls the content for that page. When you turn the page to look at it, I turn the next page and it goes against that page from the database.
That's a much more scalable system for us, and certainly allows us to keep things from getting out of date and we can fix things when they break. I've literally had people say, hey, this typo here is like, oh shoot, you're right, let's go fix that. And five minutes later it's published on the web portal. It's a much more versatile system for us.
Cruce Saunders
That's great. So it really allows changes to the reader experience without altering the content itself, because there's an ability to work with those templates independently of the content. And then there's also a way to work with the content independently of the templates.
Mike Hedblom
Exactly. In this case, we're using the Heretto portal to generate a website of documentation. We have a documentation portal. It's all of our product documentation. It's all being served up through Heretto Portal. The portal itself knows how to render the HTML. It has templates for what the pages look like. It has templates for the navigation pages. We accept the templates that Heretto has created for us, and they maintain it for me. I don't have to maintain those templates, which is something I used to have to do. I am so happy to not have to maintain those things anymore. Instead, all I really focus on is the style and the branding. How I want that HTML to be rendered is the stuff I focus on, and some other customizations. But it's so nice to be able to have that another degree of separation keeping me away from the content. I don't have to query the database, I don't have to generate HTML pages. All I have to worry about is how I want it looked and what filters to apply to that content when it comes out, which DITA tags to use.
Cruce Saunders
Okay, yeah. So in this case Heretto is managing the portal templating and structure. You're handling some of the presentation, CSS and display format, and then the back office CMS is actually populating the content into the template. So you're just managing the workflow, getting content in through the WYSIWYG editors, and then you're managing sort of the styling, but you don't have to deal with really kind of any of the other middleware pieces.
Mike Hedblom
Right. That's kind of what got me onto this project with herretto was I originally was building static web pages with the DITA open toolkit, and I had them highly customized, and it was just getting harder and harder to maintain. And I began to have needs, to have multiple products with different needs, and it was becoming too unusable, unworkable. So I was looking to build my own. I'm not going to use did open toolkit anymore. I'm going to build my own web server and build my own system for generating. And I looked at a number of popular systems like Hugo and Jekyll and Docusaurus, and I tried doing them myself, and I wasn't happy with them. And I was talking to the people at Heretto one day and said, I'm just really not happy with this system anymore. I'm thinking about switching to something else so I can find something better. And where they said, hey, we've got this new thing coming up, this project that they were working on that was the Heretto portal and deploy APIs. And we had talked about the APIs before, and I had thought about, okay, maybe I could use those to do my own portal software.
But when they showed me early versions, the Heretto portal, I thought, okay, that's nice, you've done a lot of the work for me, but I still want the customization, I still want control over it. But then there was one thing they had was a login button on the page. And I said, what's that for? They said, well, when you log in, we know who the user is, so we can customize content based on what we know about that user. And it was just like the light bulb went off. It's something I'd been waiting for over 20 years to be able to finally do that, to deliver content that was customized to the user, in this case, a role, or what was known about that user. And I said, I got to have that. Let's work on. This. And so we worked together to build that out and make the system that we have now. And now I can have content on a single page, like I said, that's public or private or internal, and it's just wonderful. I don't have to maintain that stuff. That's the best part for me. I don't have to build that myself.
I don't have to worry about the API calls and HTML page templates, and I can just focus on customizing what I want to do at the end.
Cruce Saunders
Yeah, we found that even on the marketing side, there's so much that can be worked towards with structure by just taking some isolated content types, like article based content, blog content, for example, and just having a starting point for componentizing and DITA structures are really good for that. And I think your story helps people understand just the ease of use that modular content can have. A technology and an approach that is built around component reassembly and minimal model for presentation based on audiences. So component based, structured content, personalization, doesn't have to be highly complex and so decoupled and so discreet with all these parts to keep track of that. It's just untenable. Right? Because I think a lot of people run away from component projects when they get into those details. But you're describing a scenario that shows how easy it is to get traction using component content within some defined content types.
Mike Hedblom
It's kind of an old trope to use Lego blocks as an example. But if you think about it, I can take some basic Lego blocks and I can build a pretty cool little model or display of something, or I can use those really advanced Lego features they have. They come out with some really amazing and build some huge, intricate, detailed models. It's still Lego blocks. And if I don't need to do all that fancy, intricate stuff, if I just need to build a little house or something, it's going to be great with the basic pieces that I have, I don't need that fancy stuff. And it's very similar to the way we use it. We've kept it real simple, but the flexibility is there. I can do things with it if I really wanted to. I can take this content and deliver PDF, or I could feed it out into another system if I had to view the APIs and do things with that. It's the potential is there. I should say there's a lot of potential in there to be able to do things. Whatever you need with it. If you have the content structure to begin with, how much structure you want to apply to it, that's whatever you feel comfortable with.
But just having that gives you so much flexibility to be able to do things you can't do. If you have just Google documents, I've seen people do things where they generate slide presentations from DITA. It's pretty cool. They just pull. I want to pull these things together. And here's a page of slide presentation. Looks like they build a deck out of DITA. It's cool to do that because you can do it with the content you've got.
Cruce Saunders
Oh yeah, we've worked with teams that have been able to take their same DITA content used for support and then bring it up into marketing content as well to get to push sort of related products. And the same thing with trying to get marketing content into tech docs to say, okay, you've got this product, continue to extend your suite with these things so that they're cross selling even within the support experience and then helping to answer questions for people that are doing product evaluations in the marketing content. Because sometimes that question and answer based content that is there to help resolve tasks is actually really good to help bring in search engine traffic for people trying to solve those problems. And then they discover, oh, this product has this really detailed approach to solving these particular challenges and then it gets them into a marketing funnel for sales to go talk to them about adopting their product. It's like there's some really good things to do between pre and post sales content and once it's modular, then you can start having those conversations internally and building some collaboration.
Mike Hedblom
Right. There was a trend about ten years ago put everything into a database, put everything into your CMS and then we can magically do things with it. And I didn't see too many companies really doing that, but at least in the software industry, I'm sure that there were companies doing it. I'm sure that it has been done, but it just seemed like that died out from my perspective from where I am. But the concept was sound. The concept is have a content management system which is in our case, what Heretto is it's just storing that data and allowing me to access it and use it however I need to use it. That's the key to if I can grab that stuff and put it together the way I need to use it, then it's useful information. I always had this idea of all the strings, all the labels that you see in a software product, everything in the UI where it says any kind of text I wanted to see that be in the CMS. And so when they build the software, you pull it out of the CMS and put all the labels on the screen.
That then allows me writing the product documentation to use those same labels. So I can say, here's all the elements that build up that screen. Click on the submit button. Now if somebody comes along in the software and changes that word "Submit" to be "Send", it would automatically change the UI in the software and it would change my documentation as well because we're using the same piece of information. That to me was like the power of this stuff that I haven't really seen anybody do, but it's potentially there to do that. It's the same thing as you were saying with the marketing material and sales material, the support material. Here's the piece, use it. I can pull this thing in and it's going to say the same thing in the marketing material that it says in the product documentation. We're not going to be calling it different things, we're not going to be describing it differently.
Cruce Saunders
Yeah, well, the groundwork is laid. I'm curious about what you see ahead for your journey with modular content and some of the things that you'd like on your forward roadmap in the coming years.
Mike Hedblom
Yeah, I think I kind of hinted it. I'd really like to be able to have more dynamic selection so that a user, a reader visitor of my doc site, can say the type of content they want to see and filter it and change it to be just the stuff they are interested in. We have a lot of product integration going on where different products are talking to each other right now. That's kind of siloed between the two different products. I have to look in one product versus another product. I would almost like to say, well, I want to talk this feature and I want to talk about the cross product. I'd like to be able to filter that way to be able to have it tell me I could do that. I think that's kind of the future where we're going to go with this. Right now a lot of that problem is solved with Search. 99% of the visitors to our website use search to navigate around in the site. We spend all this time laying out our sitemaps and how we want them to do. Everybody comes in and they use search to find the topic they're looking for.
They're not going to bother clicking down through some stuff to find it. In our case, our search results show us not just our product documentation. If you're a Medallia employee, it also shows you the support, knowledge base and community comment as well. So when I'm looking for an answer on the documentation portal, I'm actually searching our knowledge base managed by support and I'm searching our developer portal and other portals as well for the information. And that's a lot of the key to be able to pull that information in from various different silos and say, what's the answer I'm looking for? And then not just have a list of 100 different topics, but to have it ranked in such a way that the system knows these are the popular topics or these are the ones that you're probably looking for and I'm expecting to see more of that. There's lots of talk about AI and chat.
Cruce Saunders
Yeah, I was going to ask you about that.
Mike Hedblom
I go back and forth on that. There's a lot of really interesting things that could happen there for example, our documentation would tell you how to create a user account and separately would tell you how to assign permissions to a user account. And separately from that, it might tell you if I want to look at a certain type of report, what permission do I need to have to see this type of report. Nowhere in my documentation does it say I need to create a new user account and I need to give them permission to see this type of report. I don't have a series of steps that tell you how to do that very specific task where a chatGPT would say, I can go pull that information out from the documentation and give you the specific steps for that task which are not documented anywhere. That I think is going to be really cool. Beyond that, I'm not really seeing yet how to do it. I can see some people using it for authoring to get to build some ideas up on how to write a concept or things along those lines.
And there's a lot of people doing some really cool stuff with it. I'm not seeing yet how it's really going to play out. And that's me. I've got an eight year old iPhone. I'm not always the most technically savvy, advanced person, but when I know I want to do something, I'm going to go figure out how to do it. I'm going to find somebody who's either done it or I'm going to go try something out and say, let's do it. I'm just not there at the moment. With the chatGPTs for our Doc site, Heretto's got an interesting new product coming out to do that. It's a chat feature they call Etto, and it's pretty cool because it knows how to read just your content in your database and your CMS, and it builds content based on that. I'll be curious to see where that goes.
Cruce Saunders
Yeah, I think conversational interfaces with content are going to be more and more the norm for anyone that is dealing with users that are engaged in a problem solving activity where navigation behavior and search behavior is actually in the way of accomplishing the task.
Mike Hedblom
Yes so much of the problem is knowing how to phrase the question. Even with the chatGPTs, a lot of them is how do you phrase your question to get the most out of it? It's the same problem with search, though. How do I put in a Google search to find exactly what I'm looking for? You learn over time how to do that, but you really want to be able to just have that conversational aspect to it. And then most importantly is the conversational piece of it is to be able to refine your previous question. And that's what's missing from current search technology, is to be able to refine the previous search, say, oh, not just show me the ones that have this. Can you back up and expand it and show me topics that cover this area as well. That's going to be the real power of that stuff and to have this conversation.
Cruce Saunders
Yeah. And it makes me feel like the actual nirvana end state isn't all of the above strategy. It's not necessarily that our navigation based approaches get replaced entirely by chat but that there's intelligent agents that help users to accomplish tasks. And users also have the ability to work with content in an on demand way that is being presented through their search experience, their sort of traditional search experience or navigation experience so that any way you get to it, you're accomplishing. The objective is to get the user to accomplish their task with high signal content that's relevant and in context with the minimum of confusion or extraneous information because sometimes users have to dig through so much stuff that they didn't want in order to get to the goody. And so we want to eliminate all that as much as we can. And so I think having structured modular content available for re-presentation and for the chat bots to make use of and it seems like the right mix, right?
Mike Hedblom
And what's going to really help those chat bots is if the content is tagged in a way to say to assist those chat bots I have here some conceptual information or I have here some reference information or here's a series of tasks. If you can tell the chat bot that that's what the type of content is, it's going to make the results smarter and better and help @mikehedblom And there again is back to tagging content in DITA, having that metadata, having just the semantic tagging behind things. This is a heading, this is not just bold text that I have in here. This is my paragraph, this is my section applying to this topic. All these semantical things are what's going to make those conversational systems produce better results. Instead of having just a wall of text, I've got a wall of tagged content that's going to be able to allow it to make a better result. If you've got the information and you've got the appropriate metadata associated with it, you can do really cool things with it in the end and it's going to just make these conversational chats give them better results when they're produced.
If you can tell the chat bot that that's what the type of content is, it's going to make the results smarter and better and help @mikehedblom
Cruce Saunders
Yeah. So you're already doing cool things with content and more cool things up ahead. I think that's a great place to leave it. I would love to wrap with just any thoughts that you have for folks considering a move to component based content, especially folks that might have been a little bit afraid of the complexity involved in the perception of oh, this is just going to be too much work. What advice do you have for folks considering that move?
Mike Hedblom
One of the things that kind of gets in trouble is you often have to make something fast and make a solution go forward and understand that I've got a problem. I just need to get this problem solved. Now, sometimes a little planning and forethought is going to help you down the road, make it much better decisions. And what I mean by that is DITA can be seen as overkill. If I'm a single product company and I'm just doing this one widget, having a DITA solution might feel like overkill. There's other systems I could probably use that would be just as easy to use. But if you're going to grow your company and have multiple products, and you're going to have multiple, maybe acquisitions, and you're going to get bigger and you're going to become an enterprise, it's so much easier. Just if you've got your content already in that format where you can work with it and retag it and do stuff with it. So I'm not saying you have to use DITA, but if you really think you're going to grow your content, if you're going to get bigger and do a lot with it, start out with something like DITA, because the flexibility is there @mikehedblom and you're not going to get trapped. You're not going to get stuck doing something you're going to regret later on.
if you really think you're going to grow your content, if you're going to get bigger and do a lot with it, start out with something like DITA, because the flexibility is there @mikehedblom
Resources themselves, I would say, depending on how far you want to go, find a consultant to work with. If you're first starting out with this and find one that's going to work with you the way you want to go with your vision, rather than have them tell you how to do things, have them tell you how to do the things you want to do. It's more what I would look for in that case, there's lots of conferences, there's lots of discussions, there's blogs, all kinds of people who talk about this stuff. There's a excellent writer named Tom Johnson who does a blog called I'd Rather Be Writing.
Cruce Saunders
Yeah, he's been on this podcast.
Mike Hedblom
Yes.
Cruce Saunders
Great.
Mike Hedblom
Yeah, Tom is a really great person. I really enjoy him. He's a great source of knowledge for anything to do with pet communication and content delivery system because Tom is always out there on the bleeding edge trying new stuff. I enjoy reading his stuff. I enjoyed meeting him in the past. There's the write the docs slack community. If you have questions about how to do and it's not just that's all forms of documentation. So there's people in there talking about that know how to do stuff, they've done it. So if you want to say, hey, I'm thinking about switching over to a structured based content, who could I talk to? You're going to get 40, 50 people there that will tell you some really good sources on how to do that stuff.
Cruce Saunders
Yeah. No, you're inspiring in your practical approach, and I really appreciate you sharing the successes you've had with working with structured content with the Heretto platform and with your journey to getting your authors to work with structure in the easiest possible way. And some of the great work that you've been able to actually ship version one, two, three rather than just having in that planning stage forever. So it's great to see that practical, real life, ployed approach through your eyes. Thanks for sharing that with our listeners on Towards a Smarter World.
Mike Hedblom
You're very welcome. It was a pleasure. Enjoyed it.
Cruce Saunders
All right, thanks, everybody. Appreciate you getting to chime in, and if you have any questions, ideas, or thoughts about structured content you'd like to further explore on this program, please reach out. We'd love to hear from you and build more episodes around your interests. And if you have any experience with structured content programs that you would like to share with listeners, also reach out. We're looking for additional guests to help explain this world of moving towards a smarter world one step at a time, like Mike has done, and we appreciate his time today. Thanks, everyone. Have a great day.
Welcome to towards a smarter world I'm your host, Cruce Saunders, and today's episode is part of our series looking at content leaders and the composable revolution. We're fortunate today to learn from Mike Hedblom from the technical documentation community and we're going to discover how tech doc teams work with structured content and look at how that relates in some ways to the marketing side of the house as well. Mike is the Senior Director of Documentation at Medallia. A leader in experience management software. He has over 35 years of experience in the software industry, covering a lot of territory and change, both with writing and leading international teams, developing online documentation solutions. Mike lives in the Silicon Valley and has worked for a number of different industry leading companies and startups. Welcome, Mike. Thanks for being here.
Mike Hedblom
Thank you. Glad to be here.
Cruce Saunders
Well, I hear you've got an interesting modular content project going on now, and that you're responsible for really that whole content supply chain that generates personalized content. So that means you're driving the customer iterations and the content components that are assembled based on the audiences that interact with it and access that content. So you're dealing with content assemblies. Can you tell us a little bit more about that project?
Mike Hedblom
Sure. What we're talking about is, in this case, the product documentation for our various products. Medallia has a number of products. Each of them has varying degrees of software documentation. In addition to having different audiences of developers and administrators and users, we also had a need to have content that is internal for Medallia only to see. And we had content that we didn't want out on the public website. We wanted it to be able to access through a login so that certain customers can only see information once they've logged in. So that was the solution that we were trying to achieve. We finally are doing now we're doing all that with Heretto's CMS and Heretto's deploy portal software.
Cruce Saunders
So can you tell me where did the project begin? What was the seed that really initially moved everybody towards modular content? Sounds like these three different audiences, each needing to have access to different versions of the content, was one of the seeds. Were there any others?
Mike Hedblom
Yes. There's a number of things that got us going on this project. Stepping back. When we first created the Medallia product documentation, we decided to go with DITA. It was about eight, nine years ago as a format because it allowed us such flexibility. Some of the beauties of using DITA content is that it's very modular, very semantically organized. And in addition to that, you can tag the content with various attributes @mikehedblom One of the attributes you can say "for this piece of content, what is the audience?". In our case, we define an audience as public, private, or internal. So in the content itself, we've already flagged who can see this piece of information. And we went with DITA for a number of reasons. One of them primarily at the time, was we wanted to be able to reuse content. So we have lots of cases where there is something that is said in one place and we need to say the same exact thing in another place. Traditionally, you might copy and paste that, and over time, somebody else comes along and takes one of those things and makes a change to it. So now you've got divergence between the content with DITA, it allows you to actually use one piece of content and have it appear wherever you need it to appear multiple times.
Some of the beauties of using DITA content is that it's very modular, very semantically organized. And in addition to that, you can tag the content with various attributes @mikehedblom
And that was really important to us because we had a lot of reference material where there was a lot of duplicate information. We wanted to be able to say that once. Part of the advantage of that saying it just once is that if you localize the content, translate it, you only have to translate it once instead of ten or 20 times or 40 or even 100 times across multiple different pages of documentation @mikehedblom Instead, you're just translating the source one time. So that got us going in that direction initially, why we went with DITA. Eventually our current solution allowed us to publish pages of content, pages of documentation using those attributes I was talking about, those tagged attributes to say that "only show this content to an internal user", or "only show this content to an authorized restricted user", one of our customers. And that's the solution that we have now. We have a single website for our product documentation, same URLs, everything, but different people might see different content on that same URL based on what we know about them. And that was key for us. That's the big advantage to us. We can show internal notes or instructions to employees that do not appear when the user page or a customer page, but the same page when an employee looks at will see the instructions on what they need to do.
if you localize the content, translate it, you only have to translate it once instead of ten or 20 times or 40 or even 100 times across multiple different pages of documentation @mikehedblom
Cruce Saunders
Okay, so your team started out with a content architectural approach, building with a public content model in DITA. Can you tell us a little bit more about for the folks that don't know what DITA is, (Darwin Information Typing Architecture). What is it and why did you end up deciding that DITA was the best architecture to move with?
Mike Hedblom
DITA itself gives us the greatest flexibility in terms of being able to put documentation together. It allows us to have pieces and assemble them at the time we want to publish them, so we don't have to have long documents of content. We can have an overview. We can have a separate piece that's a reference. We might have tasks. The DITA architecture really is a way of classifying content, semanticly identifying it. And there are people who are very evangelical about how to use DITA. And you say this is a piece of overview, content or concept, this is a task and this is a reference and you use all those features. And when you use those classifications there is again semantical information that's specific to that type of content. If I have a task element, for example, a task is going to have steps in it. And so when you're working with the content you say here's a step and here's a sub-step and there's information about the step. So it's a way of classifying each of those pieces of content. If you at all familiar with HTML, or just even simply if I'm looking at a document of text, I'm just looking at it, I might see a paragraph, I could see bold text, I might see italic text, I could see headings.
Each of those things is a semantic element in DITA. What's nice though about what we use with Heretto is that's all obfuscated, it's all hidden behind the scenes. I get to use a simple GUI editor just like you would see with Word or with Google Docs or something like that. And I edit my content and I just write it and it looks like a printed page, like a WYSIWYG page, but behind the scenes it's all tagged, has the semantic information behind it that allows us to then assemble and reassemble it and do things with it that you can't do with other with Word documents or Google Docs type of thing.
Cruce Saunders
So it's enabling automation, translation, analysis, transformation, lots of different actions that you can take with these content modules. So these different chunks, these topics that are reusable in different ways than documents and that is something that lends itself to these scenarios that you're talking about, where content needs to be targeted to public private customer use and internal employee use.
Mike Hedblom
We don't do it, but a lot of companies use DITA. Even beyond that, we're just focused on product documentation. But if you follow the DITA model and you follow content modeling, you can use the same content for your training material, you can use it for your marketing material, for your sales material and that way you've got a single source of truth for all the content that you produce in your company. We don't use that model, but it's a very common model and I've seen people do it and it's really impressive. It's nice to be able to say what a particular feature is and have a description of it and be able to use that same description across the corporation @mikehedblom
It's nice to be able to say what a particular feature is and have a description of it and be able to use that same description across the corporation @mikehedblom
Cruce Saunders
Yes. We work with a number of clients who are doing cross departmental content reuse between presales content and post sales content so that there can be a continuous customer experience. For example, using the same semantics to tag up different content chunks that are related to the same product. Customer intent. Like the thing that the customer wants to do with that part of the product. Some of that might be marketing material and some of that might be support material, but it all has to be assembled based on what the customer's context is. And so in those cases we've built content models that incorporate DITA but might also have other logical structures that meet the needs of a particular marketing funnel. It starts to get into more content orchestration at that point. But it's like DITA is an excellent foundational piece that can be used out of the box. And it sounds like you really have gotten a lot of value from using DITA and its native structures without needing to specialize it or extend it too much. Is that right?
Mike Hedblom
Yes. In fact, DITA has what they call a topic. Everything is a topic. And then they have specializations that I mentioned, concepts and tasks and references. By default they have other specializations as well. We don't use those in our company. We just use everything as a topic. We didn't want to get into customizing the existing stuff, we just wanted to keep it real simple. Can we just use what DITA provides us out of the box? And so almost everything we do is a topic. So we've actually begun to look at using tasks and we've started using the task things because it came out real nice for some of the things we wanted to achieve for some of the more task based topics that we have. But we completely avoided the specializations, customizing it ourselves and that made understanding how to use it much simpler. You just have to learn a few simple things.
Cruce Saunders
No, I love that it's a very practical way to get started with structured content to demonstrate value very quickly and accomplish some really clear business goals. Right. We got to get content to multiple audiences.We don't want to rewrite it on a bunch of different pages. So what's the most efficient way to do that? @mrcruce And it turns out you found in real life DITA is working for you to do that. I wanted to talk a little bit about the tagging because you mentioned that you had flagged content based on who can see it and so you those tagged attributes on the individual topics, is that right?
We got to get content to multiple audiences.We don't want to rewrite it on a bunch of different pages. So what's the most efficient way to do that? @mrcruce
Mike Hedblom
We take it down to a very small granular level actually we can tag a topic. We can tag an entire section we'll call a "map" of all the topics within a group, like a collection. We can say that they all get the same tag, but we can take it down to a very granular level. In some of our release notes, we tag a bold attributes on the bold in some of our content. So only the internal audience sees something as bold. The customer does not see something as bold. In fact, they don't even see that content. The flexibility is amazing what we can do with it. We can take it from the very highest level. An entire section of the website is blocked out down to can I see this old text or not? The power was just wonderful in that regard, it gives so much flexibility.
Cruce Saunders
Is there other kinds of attributes you've extended beyond the permission attributes? So other kinds of metadata that you're attributing to these different components?
Mike Hedblom
Not really. At the moment I would like to be able to go further with it and that's kind of my next version of it is to be able to have this is administration documentation, administrator document, this is developer documentation, this is end user documentation and to be able to tag that. And I would like to be able to have on the doc portal the ability to maybe say, just show me the developer content. I don't want to see this stuff or hide developer content from end users because it's just not worth it to show them that content. That's my vision for the future is to be able to do that as well. So we're not doing that yet. I think we're going to get there eventually. We do use other attributes, but nothing else meta that really surfaces through like that.
Cruce Saunders
Okay, yeah, we see some organizations that have metadata profiles that are way bigger than the content itself. There's some organizations that just go nuts with metadata, but it sounds like your general strategy is sort of minimally viable metadata.
Mike Hedblom
Yes, we really do focus on keep it simple. We've started to look at a number of times, should we classify content so that we know if this piece of content, this topic is related to reporting. So we maybe say this is a reporting tag. Or these are things that help you when you need to understand reporting, or these are things that help you with account administration. And every time we start to look at that, we end up backing off because we don't really see how we want to apply it. And that's always the goal for us is what is it we want to do with this information and will we actually use it? We could spend a lot of time going through tagging things with a taxonomy, but if we never use it, why bother, right?
Cruce Saunders
Yeah. If metadata was in a forest and nobody actually used it, did it make a sound, right or whatever? There's a real interesting thing that happens in content architecture and planning engagements where we start creating for all the things that content could do in the future @mrcruce And it sounds like your general ship first approach is get it out there working and then incrementally improve it. As the universe says, this is necessary.
There's a real interesting thing that happens in content architecture and planning engagements where we start creating for all the things that content could do in the future @mrcruce
Mike Hedblom
I've always told my staff and teams that I've worked on, I used to call Mike's Rules of Software. And rule number one was you've got to ship version one if you ever want to get to version two. So many people spend so much time perfecting the first thing that they never get a chance to fix it and see what works and doesn't work out. Here in Silicon Valley, there's a lot of move fast and break things or fail fast, that type of thing. I don't want to fail, but we're going to fail. But we want to learn from it and let's take what we've got, learn, see what works and doesn't work and how can we improve it. It may come back to bite me someday that we didn't spend more time on a taxonomy and, oh, now we've got to go back and recategorize and tag things. But for now I've got a small team and we don't have time for that. We need to ship content. We need to get it out there, and this is the system that allows us to do that.
Cruce Saunders
Yeah, and there's probably some rule of Silicon Valley that I haven't heard published yet where if you wait long enough, AI's will eventually do it anyway.
Mike Hedblom
Where's the AI get its content. That's what I always wonder. It's got to get it from somewhere. If you have a new software feature, where's the AI going to learn about that feature so that it can tell you about it? So we're still going to have content producers.
Cruce Saunders
Well, let's talk about the content producers. Actually, I'm really curious about what that has looked like for them when you move to DITA. I mean, that's been a while now, but what advantages do they see? I mean, a lot of authors, if they come from an unstructured background, they're used to just working in Word and so using DITA, there is a behavior change that you're making. You're using structured content of any kind. There's a behavior change because you're templatizing content so that modular writing can be new for folks that aren't trained tech docs from birth right, a lot of folks come into writing documentation that don't necessarily have that formalized background. So I'm curious about how that process worked with your team and what some of the challenges are that they faced, and how it's gone.
Mike Hedblom
It goes back to why we originally chose Heretto. I really wanted writers to be able to work, authors to be able to work without having to understand the underlying source. And what I mean by that is, I didn't want them having to go into source code and write and see tags and understand the various things. I really wanted that hidden. I wanted them to just focus on writing. And so having a WYSIWYG interface where I can just write and see things and not have to understand the underlying structure was so important. I can sit anybody down who has ever worked with Google Doc or Word and I can have them write content and they can produce content very simply and easily with Heretto you already know how to do bold and italic there's little menu icons you can click on for that and it makes it bold. You see the italic and you want to lay out a table? Fine, here's a table. All that stuff is there. So they don't have to understand DITA behind the scenes and structured content in general. I'll just say, so just write the stuff out. Then we'll start working on how to tag it, how to do these things with it.
We tend to write longer topics instead of short modular chunks. There's a theory of some people should write just a small chunk of topics and a chunk of that and that way you can pull them all together and reuse them. And we tend to write longer articles in part because that's what our audiences' like. But the learning is not that hard for somebody bringing them in. I can teach them the basics in an afternoon. The people that I actually have the harder time with are the people who are pretty technically savvy and understand what's going on in the background because they want to get into the source code and see it and change it and do it the way they want it. They want to format the source code the way they want to see it indented. And it's like, oh my gosh, I want to take that source code editor away from them. It's just right, I hired it. Right? It's kind of funny because you do see that people have opinions on how things should be structured in a structured document. And if you can hide that from them and just say, I've got some content, here's a paragraph, I'm going to start a section now and the section has a title and things like that. That's a much easier person to work with than somebody sometimes who's got a lot more experience.
Cruce Saunders
Yeah, the intuition is such a key thing. It sounds like this is an intuitive solution for editing DITA that lets people write and edit DITA topics without ever learning XML. So they don't have to be DITA experts, they don't have to look at code even. And I feel like that's really a good lesson for all of those folks working in structured and modular content platforms across the board is to move closer and closer to this intuitive WYSIWYG ideal and still capture semantically enriched structure. And that's always the interesting line to walk down is how do you get just enough structure and capture it in an intuitive way so you stay out of the author's way, make it as smooth, as easy as possible, but also have enough componentization for the machines to be able to work with behind the scenes.
Mike Hedblom
Right? That's where if we were a stronger DITA house, I might have to spend more time with them. Okay, are you going to create a concept now or are you going to create a task? So let me explain the difference between the two of those things. I don't have to do that. I can say you just go to this menu and say, I want to create a topic now. Here you start writing, give it a title and start typing away. Having that semantic content really does give us a lot of flexibility. There are things that the more seasoned, the more experienced of my staff who really know how to use this stuff. They can do some pretty amazing things. I'm often impressed by, wow, how'd you do that. We have content where the same pages basically appear in two different manuals in the same project. On one project we have to call it Product A, and the other we have to call it Product B. So these are variables that we can set up in the project, and the system just says, okay, in this project I'm using variable A, and this one, I'm using variable B.
Even though it's the same source page that we've got, we're just publishing it differently as if it's in two different pages. That's the type of complexity of things you can do with it. Pretty cool when you get into it, but you don't have to know that. And that's the nice thing about it. For me, as an architect manager of the system, I can decide how far I need somebody to go and I can work with them on it. But for the most part, my team is just producing content and they don't ever really have to get into that. I've only got a small subset of the team that really kind of gets into that and says, wow, I can do these cool things with it.
Cruce Saunders
Yeah, no, that's great. So walking that balance is something you've been able to successfully mediate so far. I'm curious about the way content is being presented. So once content is inside of your system, inside of Heretto, it's structured, it's modular, and then it gets presented out to your documentation portal. So I'm curious about that system architecture from the listeners in our audience that are focused on the marketing side of the house. There's a big movement towards API delivered content. This kind of the composable revolution where we're delivering content-as-a-service via these APIs that allow for content to be queried and then presented in many, many different formats and ways. I'm kind of curious about how that is working coming out of Heretto and how your tech docs portal actually comes together and how much you work on the presentation side.
Mike Hedblom
Sure, sure. There's the underlying CMS, the content management system, which is the Heretto provides where all of the data and content are stored. And we never see that database. It's all behind the scenes, but all of our DITA content is stored in a database. And when we go to use the editor, the editor itself, it knows how to go ask the database, give me this content. And as I'm typing new content in, it says, here's some new content for the database. The CMS. Again, my team doesn't know anything about the fact it's a database behind it. They just write in the editor. It's a similar thing for the presentation. There's an application framework that we use, called Heretto portal. Which knows how to query the database for content, for pages to be rendered as HTML. So when somebody says, I want to see the page on this product, I click a link, that Heretto portal goes to the database, requests the content, it's properly filtered based on the APIs, and it's delivered to the Heretto portal software, which then renders it into HTML and sends it to the client browser. So the separation there of the web application from the source content.
Traditionally what we would do is we would go through that source content and build out static HTML pages and then deliver those HTML pages and say here's our documentation. What this system allows us to do is to actually query the database at the time the page is requested and build the page that way so that we can change content anytime and get the most recent content. And you're not having to deal with these static web pages that are suddenly out of date. The nice thing about that though, is you could use other systems to do something similar. Other systems could also be hitting those APIs and requesting data, and only authorized content would be delivered through those APIs. It's a really interesting way to deliver content instead of publishing it's like printing a manual, printing a book, instead of going out and printing the book and saying here you are, it's done. Oh, now it's out of date already. It's more like I turn the page and it goes out to the publishing system and pulls the content for that page. When you turn the page to look at it, I turn the next page and it goes against that page from the database.
That's a much more scalable system for us, and certainly allows us to keep things from getting out of date and we can fix things when they break. I've literally had people say, hey, this typo here is like, oh shoot, you're right, let's go fix that. And five minutes later it's published on the web portal. It's a much more versatile system for us.
Cruce Saunders
That's great. So it really allows changes to the reader experience without altering the content itself, because there's an ability to work with those templates independently of the content. And then there's also a way to work with the content independently of the templates.
Mike Hedblom
Exactly. In this case, we're using the Heretto portal to generate a website of documentation. We have a documentation portal. It's all of our product documentation. It's all being served up through Heretto Portal. The portal itself knows how to render the HTML. It has templates for what the pages look like. It has templates for the navigation pages. We accept the templates that Heretto has created for us, and they maintain it for me. I don't have to maintain those templates, which is something I used to have to do. I am so happy to not have to maintain those things anymore. Instead, all I really focus on is the style and the branding. How I want that HTML to be rendered is the stuff I focus on, and some other customizations. But it's so nice to be able to have that another degree of separation keeping me away from the content. I don't have to query the database, I don't have to generate HTML pages. All I have to worry about is how I want it looked and what filters to apply to that content when it comes out, which DITA tags to use.
Cruce Saunders
Okay, yeah. So in this case Heretto is managing the portal templating and structure. You're handling some of the presentation, CSS and display format, and then the back office CMS is actually populating the content into the template. So you're just managing the workflow, getting content in through the WYSIWYG editors, and then you're managing sort of the styling, but you don't have to deal with really kind of any of the other middleware pieces.
Mike Hedblom
Right. That's kind of what got me onto this project with herretto was I originally was building static web pages with the DITA open toolkit, and I had them highly customized, and it was just getting harder and harder to maintain. And I began to have needs, to have multiple products with different needs, and it was becoming too unusable, unworkable. So I was looking to build my own. I'm not going to use did open toolkit anymore. I'm going to build my own web server and build my own system for generating. And I looked at a number of popular systems like Hugo and Jekyll and Docusaurus, and I tried doing them myself, and I wasn't happy with them. And I was talking to the people at Heretto one day and said, I'm just really not happy with this system anymore. I'm thinking about switching to something else so I can find something better. And where they said, hey, we've got this new thing coming up, this project that they were working on that was the Heretto portal and deploy APIs. And we had talked about the APIs before, and I had thought about, okay, maybe I could use those to do my own portal software.
But when they showed me early versions, the Heretto portal, I thought, okay, that's nice, you've done a lot of the work for me, but I still want the customization, I still want control over it. But then there was one thing they had was a login button on the page. And I said, what's that for? They said, well, when you log in, we know who the user is, so we can customize content based on what we know about that user. And it was just like the light bulb went off. It's something I'd been waiting for over 20 years to be able to finally do that, to deliver content that was customized to the user, in this case, a role, or what was known about that user. And I said, I got to have that. Let's work on. This. And so we worked together to build that out and make the system that we have now. And now I can have content on a single page, like I said, that's public or private or internal, and it's just wonderful. I don't have to maintain that stuff. That's the best part for me. I don't have to build that myself.
I don't have to worry about the API calls and HTML page templates, and I can just focus on customizing what I want to do at the end.
Cruce Saunders
Yeah, we found that even on the marketing side, there's so much that can be worked towards with structure by just taking some isolated content types, like article based content, blog content, for example, and just having a starting point for componentizing and DITA structures are really good for that. And I think your story helps people understand just the ease of use that modular content can have. A technology and an approach that is built around component reassembly and minimal model for presentation based on audiences. So component based, structured content, personalization, doesn't have to be highly complex and so decoupled and so discreet with all these parts to keep track of that. It's just untenable. Right? Because I think a lot of people run away from component projects when they get into those details. But you're describing a scenario that shows how easy it is to get traction using component content within some defined content types.
Mike Hedblom
It's kind of an old trope to use Lego blocks as an example. But if you think about it, I can take some basic Lego blocks and I can build a pretty cool little model or display of something, or I can use those really advanced Lego features they have. They come out with some really amazing and build some huge, intricate, detailed models. It's still Lego blocks. And if I don't need to do all that fancy, intricate stuff, if I just need to build a little house or something, it's going to be great with the basic pieces that I have, I don't need that fancy stuff. And it's very similar to the way we use it. We've kept it real simple, but the flexibility is there. I can do things with it if I really wanted to. I can take this content and deliver PDF, or I could feed it out into another system if I had to view the APIs and do things with that. It's the potential is there. I should say there's a lot of potential in there to be able to do things. Whatever you need with it. If you have the content structure to begin with, how much structure you want to apply to it, that's whatever you feel comfortable with.
But just having that gives you so much flexibility to be able to do things you can't do. If you have just Google documents, I've seen people do things where they generate slide presentations from DITA. It's pretty cool. They just pull. I want to pull these things together. And here's a page of slide presentation. Looks like they build a deck out of DITA. It's cool to do that because you can do it with the content you've got.
Cruce Saunders
Oh yeah, we've worked with teams that have been able to take their same DITA content used for support and then bring it up into marketing content as well to get to push sort of related products. And the same thing with trying to get marketing content into tech docs to say, okay, you've got this product, continue to extend your suite with these things so that they're cross selling even within the support experience and then helping to answer questions for people that are doing product evaluations in the marketing content. Because sometimes that question and answer based content that is there to help resolve tasks is actually really good to help bring in search engine traffic for people trying to solve those problems. And then they discover, oh, this product has this really detailed approach to solving these particular challenges and then it gets them into a marketing funnel for sales to go talk to them about adopting their product. It's like there's some really good things to do between pre and post sales content and once it's modular, then you can start having those conversations internally and building some collaboration.
Mike Hedblom
Right. There was a trend about ten years ago put everything into a database, put everything into your CMS and then we can magically do things with it. And I didn't see too many companies really doing that, but at least in the software industry, I'm sure that there were companies doing it. I'm sure that it has been done, but it just seemed like that died out from my perspective from where I am. But the concept was sound. The concept is have a content management system which is in our case, what Heretto is it's just storing that data and allowing me to access it and use it however I need to use it. That's the key to if I can grab that stuff and put it together the way I need to use it, then it's useful information. I always had this idea of all the strings, all the labels that you see in a software product, everything in the UI where it says any kind of text I wanted to see that be in the CMS. And so when they build the software, you pull it out of the CMS and put all the labels on the screen.
That then allows me writing the product documentation to use those same labels. So I can say, here's all the elements that build up that screen. Click on the submit button. Now if somebody comes along in the software and changes that word "Submit" to be "Send", it would automatically change the UI in the software and it would change my documentation as well because we're using the same piece of information. That to me was like the power of this stuff that I haven't really seen anybody do, but it's potentially there to do that. It's the same thing as you were saying with the marketing material and sales material, the support material. Here's the piece, use it. I can pull this thing in and it's going to say the same thing in the marketing material that it says in the product documentation. We're not going to be calling it different things, we're not going to be describing it differently.
Cruce Saunders
Yeah, well, the groundwork is laid. I'm curious about what you see ahead for your journey with modular content and some of the things that you'd like on your forward roadmap in the coming years.
Mike Hedblom
Yeah, I think I kind of hinted it. I'd really like to be able to have more dynamic selection so that a user, a reader visitor of my doc site, can say the type of content they want to see and filter it and change it to be just the stuff they are interested in. We have a lot of product integration going on where different products are talking to each other right now. That's kind of siloed between the two different products. I have to look in one product versus another product. I would almost like to say, well, I want to talk this feature and I want to talk about the cross product. I'd like to be able to filter that way to be able to have it tell me I could do that. I think that's kind of the future where we're going to go with this. Right now a lot of that problem is solved with Search. 99% of the visitors to our website use search to navigate around in the site. We spend all this time laying out our sitemaps and how we want them to do. Everybody comes in and they use search to find the topic they're looking for.
They're not going to bother clicking down through some stuff to find it. In our case, our search results show us not just our product documentation. If you're a Medallia employee, it also shows you the support, knowledge base and community comment as well. So when I'm looking for an answer on the documentation portal, I'm actually searching our knowledge base managed by support and I'm searching our developer portal and other portals as well for the information. And that's a lot of the key to be able to pull that information in from various different silos and say, what's the answer I'm looking for? And then not just have a list of 100 different topics, but to have it ranked in such a way that the system knows these are the popular topics or these are the ones that you're probably looking for and I'm expecting to see more of that. There's lots of talk about AI and chat.
Cruce Saunders
Yeah, I was going to ask you about that.
Mike Hedblom
I go back and forth on that. There's a lot of really interesting things that could happen there for example, our documentation would tell you how to create a user account and separately would tell you how to assign permissions to a user account. And separately from that, it might tell you if I want to look at a certain type of report, what permission do I need to have to see this type of report. Nowhere in my documentation does it say I need to create a new user account and I need to give them permission to see this type of report. I don't have a series of steps that tell you how to do that very specific task where a chatGPT would say, I can go pull that information out from the documentation and give you the specific steps for that task which are not documented anywhere. That I think is going to be really cool. Beyond that, I'm not really seeing yet how to do it. I can see some people using it for authoring to get to build some ideas up on how to write a concept or things along those lines.
And there's a lot of people doing some really cool stuff with it. I'm not seeing yet how it's really going to play out. And that's me. I've got an eight year old iPhone. I'm not always the most technically savvy, advanced person, but when I know I want to do something, I'm going to go figure out how to do it. I'm going to find somebody who's either done it or I'm going to go try something out and say, let's do it. I'm just not there at the moment. With the chatGPTs for our Doc site, Heretto's got an interesting new product coming out to do that. It's a chat feature they call Etto, and it's pretty cool because it knows how to read just your content in your database and your CMS, and it builds content based on that. I'll be curious to see where that goes.
Cruce Saunders
Yeah, I think conversational interfaces with content are going to be more and more the norm for anyone that is dealing with users that are engaged in a problem solving activity where navigation behavior and search behavior is actually in the way of accomplishing the task.
Mike Hedblom
Yes so much of the problem is knowing how to phrase the question. Even with the chatGPTs, a lot of them is how do you phrase your question to get the most out of it? It's the same problem with search, though. How do I put in a Google search to find exactly what I'm looking for? You learn over time how to do that, but you really want to be able to just have that conversational aspect to it. And then most importantly is the conversational piece of it is to be able to refine your previous question. And that's what's missing from current search technology, is to be able to refine the previous search, say, oh, not just show me the ones that have this. Can you back up and expand it and show me topics that cover this area as well. That's going to be the real power of that stuff and to have this conversation.
Cruce Saunders
Yeah. And it makes me feel like the actual nirvana end state isn't all of the above strategy. It's not necessarily that our navigation based approaches get replaced entirely by chat but that there's intelligent agents that help users to accomplish tasks. And users also have the ability to work with content in an on demand way that is being presented through their search experience, their sort of traditional search experience or navigation experience so that any way you get to it, you're accomplishing. The objective is to get the user to accomplish their task with high signal content that's relevant and in context with the minimum of confusion or extraneous information because sometimes users have to dig through so much stuff that they didn't want in order to get to the goody. And so we want to eliminate all that as much as we can. And so I think having structured modular content available for re-presentation and for the chat bots to make use of and it seems like the right mix, right?
Mike Hedblom
And what's going to really help those chat bots is if the content is tagged in a way to say to assist those chat bots I have here some conceptual information or I have here some reference information or here's a series of tasks. If you can tell the chat bot that that's what the type of content is, it's going to make the results smarter and better and help @mikehedblom And there again is back to tagging content in DITA, having that metadata, having just the semantic tagging behind things. This is a heading, this is not just bold text that I have in here. This is my paragraph, this is my section applying to this topic. All these semantical things are what's going to make those conversational systems produce better results. Instead of having just a wall of text, I've got a wall of tagged content that's going to be able to allow it to make a better result. If you've got the information and you've got the appropriate metadata associated with it, you can do really cool things with it in the end and it's going to just make these conversational chats give them better results when they're produced.
If you can tell the chat bot that that's what the type of content is, it's going to make the results smarter and better and help @mikehedblom
Cruce Saunders
Yeah. So you're already doing cool things with content and more cool things up ahead. I think that's a great place to leave it. I would love to wrap with just any thoughts that you have for folks considering a move to component based content, especially folks that might have been a little bit afraid of the complexity involved in the perception of oh, this is just going to be too much work. What advice do you have for folks considering that move?
Mike Hedblom
One of the things that kind of gets in trouble is you often have to make something fast and make a solution go forward and understand that I've got a problem. I just need to get this problem solved. Now, sometimes a little planning and forethought is going to help you down the road, make it much better decisions. And what I mean by that is DITA can be seen as overkill. If I'm a single product company and I'm just doing this one widget, having a DITA solution might feel like overkill. There's other systems I could probably use that would be just as easy to use. But if you're going to grow your company and have multiple products, and you're going to have multiple, maybe acquisitions, and you're going to get bigger and you're going to become an enterprise, it's so much easier. Just if you've got your content already in that format where you can work with it and retag it and do stuff with it. So I'm not saying you have to use DITA, but if you really think you're going to grow your content, if you're going to get bigger and do a lot with it, start out with something like DITA, because the flexibility is there @mikehedblom and you're not going to get trapped. You're not going to get stuck doing something you're going to regret later on.
if you really think you're going to grow your content, if you're going to get bigger and do a lot with it, start out with something like DITA, because the flexibility is there @mikehedblom
Resources themselves, I would say, depending on how far you want to go, find a consultant to work with. If you're first starting out with this and find one that's going to work with you the way you want to go with your vision, rather than have them tell you how to do things, have them tell you how to do the things you want to do. It's more what I would look for in that case, there's lots of conferences, there's lots of discussions, there's blogs, all kinds of people who talk about this stuff. There's a excellent writer named Tom Johnson who does a blog called I'd Rather Be Writing.
Cruce Saunders
Yeah, he's been on this podcast.
Mike Hedblom
Yes.
Cruce Saunders
Great.
Mike Hedblom
Yeah, Tom is a really great person. I really enjoy him. He's a great source of knowledge for anything to do with pet communication and content delivery system because Tom is always out there on the bleeding edge trying new stuff. I enjoy reading his stuff. I enjoyed meeting him in the past. There's the write the docs slack community. If you have questions about how to do and it's not just that's all forms of documentation. So there's people in there talking about that know how to do stuff, they've done it. So if you want to say, hey, I'm thinking about switching over to a structured based content, who could I talk to? You're going to get 40, 50 people there that will tell you some really good sources on how to do that stuff.
Cruce Saunders
Yeah. No, you're inspiring in your practical approach, and I really appreciate you sharing the successes you've had with working with structured content with the Heretto platform and with your journey to getting your authors to work with structure in the easiest possible way. And some of the great work that you've been able to actually ship version one, two, three rather than just having in that planning stage forever. So it's great to see that practical, real life, ployed approach through your eyes. Thanks for sharing that with our listeners on Towards a Smarter World.
Mike Hedblom
You're very welcome. It was a pleasure. Enjoyed it.
Cruce Saunders
All right, thanks, everybody. Appreciate you getting to chime in, and if you have any questions, ideas, or thoughts about structured content you'd like to further explore on this program, please reach out. We'd love to hear from you and build more episodes around your interests. And if you have any experience with structured content programs that you would like to share with listeners, also reach out. We're looking for additional guests to help explain this world of moving towards a smarter world one step at a time, like Mike has done, and we appreciate his time today. Thanks, everyone. Have a great day.
