Podcast 56: Microcontent in Flare

In this episode of the Cherryleaf Podcast, we speak to Mike Hamilton about the new microcontent features coming to MadCap Flare. In particular, we discuss chatbots and using microcontent to improve search results. If you are a Technical Author working on a SaaS based application or a web site, then this is well worth a listen.


Now, normally what we do with the interviews is I ask the person to introduce themselves first but with this one it’s slightly, different because Rachel at MadCap said would I like to talk to you and I don’t know whether what we’re going to talk about is stuff that’s not been announced before or is in the public domain. So it’s also about asking you to introduce yourself but also to ask you to describe what it is that we’re going to talk about as well.


Go for it

All right well thank you for the opportunity I am Mike Hamilton I’m one of the founding members here at MadCap Software my official title I am the Vice President of Product Evangelism which is a very fancy kind of heavy way of saying don’t ever let your business partner pick your title when you’re away at a conference in England

Oh I was originally the Vice President of Product Management and that made sense for the first two or three years but as we grew and we added more and more products we actually had somebody on staff who needed that title and so I became the vice president of product evangelism my background

I’ve been technical writing or the software side of technical writing for probably 80% of my adult career but my education is of all things in physics and I found out way back in the 1980s when you work at a nuclear power plant and you are the one who complains the loudest about how horrible the reactor plant operation manuals are they now put you in charge of the technical publications library and that sent me kind of careening off into a whole new career direction before I knew what  technical writing was you know an actual proper career so I did kind of come in through the side door as it were

OK so that’s who I am and have been into my background what are we going to talk about today well I am on a bit of a razor’s edge as they say here because a fully MadCap Software doesn’t normally talk about upcoming releases or any that hasn’t already been released into the public domain

However this is kind of an interesting subject and interesting topic and I’ve already spoken a bit about it in a generic fashion at the TCWorld conference that we just happened in India about two weeks ago and for those who follow us our major trade show over the year a MadWorld is coming up in April so we’re kind of in this this point of time where we’re right on the cusp of the MadWorld conference and while we don’t officially announce you know future releases anybody who’s followed MadCap Software for more than about five years every year we’ve had a major release of our flagship software within a week or three of MadWorld

So if people were you know betting or guessing types saying that we’re on the cusp of a new release would probably be a pretty safe bet how is that for a non-answer answer so officially there is no announcement

Unofficially since we’re already on schedule two about this subject matter it’s a pretty safe bet there’s going to be a new release between now and MadWorld and it’s a pretty safe bet that micro content will be a core new piece of functionality

I mean that’s not officially  announced by the company yet but that’s a safe guess OK so it’s name tension as much as anything yes

so let’s start with MadCap Flare and what is it

Alright when I’m talking to non-technical writing people I don’t don’t know what content management is I just describe it as something like Microsoft Word on steroids

The whole idea behind Flare it keep authoring as easy and simple as possible yet give us all of the single source and multi-channel publishing capabilities that is required in today’s you know authoring process talking to a technical writing audience I basically say it is content management but we’ve made content management affordable and accessible to mere mortals we don’t need the the full-time programmers on the writing team anymore

So it creates help for an application of websites, policies and  procedures for an organization, that kind of thing?


I think the key distinction though is it’s anywhere where content reuse is beneficial so if I have the same content that needs to appear you know in the web site for marketing purposes in the web knowledge base for customer look up in the online help system we want to push that into a PDF full you know user manual and in a QuickStart guide the more that content reuse comes into play

I think the more important a tool like MadCap Flare becomes that make sense

I’ve just been through editing 40 Word documents and copying and pasting the same paragraphs into every 40 all of the 40 documents. And if we were able to use Flare or Doc-to-Help which is know one of your the tools in the MadCap family it would have been a lot easier, because I could have just written it once and had it single sourced and just placed a snippet or whatever in.


So micro content, what is micro content? 

This is a bit of a can of worms because the industry doesn’t really have a single proper definition at least in my opinion probably the closest or the or that we came to a proper definition or the person who gets credit for the proper definition is a gentleman by the name of Jakob Nielsen and it’s not that he invented the idea it’s just way back in the late 1990s I think he was one of the first people to recognize it as a thing and put a label on it as hey this is going to become important now the way that

Jakob referred to it is he talked about it as short reusable very succinctly headline synopsis paragraphs and for the 1990s he was pretty spot-on.

What his crystal ball didn’t really show though is that micro content as a thing has kind of morphed into multiple things so that’s why I say it’s a bit tricky to define that term alone has come to mean different things for different people.

For a technical writer it might have one meaning for a marketing manager who specializes in social media it might have a different meaning.

I’ve been doing a lot of research in the area over the last year and a half or so and now this is not an official definition but it’s one I’ve pieced together I’ve basically stolen bits from about ten other definitions people have attempted and to really simplify to define micro content you almost have to define a micro moment

And what a micro moment is just one of those dozens of small all decisions that we all have to make every day something as trivial as I’m gonna go to the market should I wear my jacket well in the old days that might have taken a bit of work but today I can just pick up my smart phone look at the cover screen and there’s a little widget there it has a little picture of a Sun and it tells me the temperature and I can say ah no I don’t need my jacket well me making that decision was a micro moment I made that decision based on the micro content that’s being displayed on my phone

I was just going to say, so it’s assisting you people doing stuff without interrupting them or getting in the way of them actually doing the thing they want to do exactly so anything that solves a micro moment to me would be micro content how is micro content delivered in ways that’s technical office or people within the software environment might see it OK well I’ll go back to my silly phone example even just a few years ago to decide if I wanted to wear a jacket or not I might have to go in my home office boot up my computer launch a web browser go to a weather site find my city and OK finally I have my information but that’s a lot of work so that’s kind of what micro content does

How can we get that person that information as quickly with as little work as possible, and so now fast forward till today you know my Samsung phone has a little widget and the neat thing is nobody writes that weather content for my Samsung phone it’s going to that website for me and they’ve just structured that website in a way that certain key pieces of information on that website you know is it going to be sunny all day what is the temperature basically those two bits get screen and displayed on my phone now so it’s still using the same content I would have found going the long form method it’s just you were cutting me having to boot the computer launch a Web browser.

That’s another kind of key benefit about micro content – how to make it as trivially easy for the consumer to get that content as possible.

So that’s kind of theoretical for more of a practical example.

If you look at Google these days even Google has recognized what if we can get people the information they need with fewer clicks.

So it used to be you would do you know bring up a browser do a web search you know, a silly example, but how to tie my shoes and you get a list of web hits and now you have to try and figure out what is a valid link to click on then you open it and you go find the content and then you have to decide does this content meet my needs.

Well for the last year or two actually longer than, that Google has created a second algorithm so they have one algorithm that does the search rankings but they have a second algorithm that says OK of those in the top ten which one has the best micro content so now when I do the search how do I tie my shoes up above the search rankings there might be a little snippet content that says you know step one put shoes on feet step two you know put laces in right and left-hand step I get like six kind of micro steps here’s how to tie my shoes that might be all the content I need I might not even need to click a web link now

So basically the folks at Google have realized if we’ve already done the search what if we give you the relevant content now that’s the end user experience what a lot of people don’t realize what Google gets credit for is not writing that content but writing the algorithm that extracts that content

If you actually do that web search how to tie my shoes you’ll find that that little snippet at the top of the Google search believe it or not does not come from the first rank link or even the second it’s like way down number five but that second Google algorithm has figured out that while yes these rank one-way for search rankings it’s the number five website that has done the best job of defining those steps in a micro content fashion and those get extracted and placed on top of the search results

So I realize that was a really long answer but hopefully have something more real-world and concrete

Again it’s both packaging content so it’s quick and easy to consume but then also if it’s packaged correctly then even third-party devices like in this case a Google search can display that content without even having to go to the main web page.

It’s things like the summaries.

If you type “USA football results” you’ll get the score straight from Google, or recipe, or how to your shoelaces, micro content is used in other situations outside of search.

It’s used in a lot of situations probably the two most well-known are for search results and then also a little bit more work but in the artificial intelligence question response chatbot type of world if you’ve used any type of customer care site these days whether you realize it or not quite often you’re just typing with a computer and the computer is feeding you kind of pre-written answers it’s rather well known as a use case of my content but it’s kind of a completely separate use case than the search and that we discussed a minute ago.

And again that’s why I said it’s kind of hard to come up with a definition because it means a little bit different things to different sense in fact

Will it involve people just happy writing having to learn how to to use XML or JSON? Are they going to get very technical or is it is it still going to be Flare in the way that people are used to using it? you just write and the complicated stuff is is behind the scenes?

Again, I’m such a horrible person to interview because the answer is both a lot of it depends on how deeply you want to go into the technology at the highest level

If I just want to emulate those Google search results where I decide ok this is the best content to display above my search results that we will be able to do in Flare without having any XML knowledge

Just use our established existing editor.

Now if you want to go all the way into things like chatbots and supporting a dialogue question-and-answer pairs we will also be able to do that happens in Flare we will be able to create those question-and-answer paired without ever having to see any XML code where that gets a little bit trickier

Though writing the question-and-answer pairs it’s only half of the solution you would still need some developer staff to actually implement the chatbot itself which would then consume the question-and-answer pairs that were authored in Flare

So there’s a couple of things from that. One is that an implication from that is even if you as a technical third don’t know what micro content is, you’ll be able to go in and create something that will be useful to your end-users without necessarily having to make a huge jump from what your existing knowledge is. You can, there’ll be a place where you can make search better than it is today.

Oh absolutely

In fact I would even go a step further a lot of people probably already have a lot of really good micro content in their Flare projects in the form of snippets that’s almost now

I mean this is a gross oversimplification so for those who are hardcore they’re already working in micro content my apologies, but you can almost think of snippets those are reusable fragments of content designed to be used inside of the Flare publishing system micro content are reusable fragments that could potentially be used even outside of the Flare publishing system

It’s kind of making your private snippets public for other devices to use

So if you’ve got a definition of what is a widget already written in Flare, will you be able to then make that content available as micro content for reuse in the chatbot without having to rewrite? Can you take what you’ve written already and then repurpose it for micro content for chatbots?


I would simply highlight the text of that definition right click on it and there’s a right-click entry create micro content

That’s as technical as it would get, well and in fact for the seasoned Flare users, I’ll can I give you a peek behind the scenes that’s actually what we’ve done in a lot of our own Flare projects that you’re going to be seeing in our own documentation.

In many cases we already had some really good snippets in use so the topic already had a paragraph that was highlighted hurt into a snippet, so now with this release our authors went into the snippets highlighted that next again and had it create micro content.

So now the exact same like you say to paragraph definition is now being used both as a snippet for our internal use, if we want to create a PDF, but it’s also used to modify search results if we’re using an external search such as Elasticsearch or even our own internal search .

So you can stack these technologies together and they will still work all.

Now here’s where it becomes a bit of a brain melter: we can even put conditions and variables inside the micro content at least at the authoring level.

So if you’ve got people where information changes if they’re professional user or a light user, or there in the UK and in the US, and you change the word so it says postage and packing for the UK and it says shipping and handling, I guess for the States, then that will also those changes will also appear in your micro content in your chat responses or your search results.

So it is that exactly.

So one of the challenges with chatbots for technical authors is there’s a couple of things one is that it generally means another source of content you’ve got to write the questions you’ve got to write the answers and they sit in their own little world completely separate from whichever tool you’re using for creating content

And the other thing it’s often using technology that is unfamiliar to for technical writers, for technical authors.

I can see an opportunity in that in that people can go to the team and say oh you’re interested in the chat well I’ve got all this content that you can use all you need to do is connect it to the technology that you’ll do the natural language searching but I’ve got the repository of all the answers to all the questions that people have

Now when I saw the demo back in December, the focus was primarily on search at this first step the sort of baby step to get people familiar with it.

Is that still the plan for this release all or their opportunities to dive into chatbots as well or is that as it were a face to thing wants people are familiar with it no the chatbot functionality will be phase one?

Well, now to kind of paint a verbal picture what you can expect to see in the upcoming Flare.

Imagine a two-part editor left column you can put in the question right column you see a pretty standard Flare editor so there’s really two different ways this can be approached.

As you say traditionally chatbots were fed just from a unique writing process.

We don’t recommend that but it will work that way you can actually open this new editor and Flare and just author question response question response

Now previously I mention kind of doing it more of a snippet eyes method or I could just go into an existing topic highlight some content and tell Flare create micro content

Well there’s a bit of you know XML sleight of hand behind the scenes

When I do that, it auto populates that question and answer panel in Flare and just automates the creations though, regardless of whether I’m typing into that question and answer screen or I’m using the more automated kind of snippet method.

It still ends up writing the same micro content files in the background and that’s where I’ll go a little bit more technical for a moment what actually gets saved as files.

Well it’s a two-part system.

The questions those actually get saved as a rather generic XML file which anybody can open with a copy of Notepad that will contain all of the questions, but then each of those questions will then link to an individual Html5 file, and those would be the answers preferably updated from the topics themselves.

If you’re doing it kind of that snippet technique, can you write lots of different questions or different ways of asking similar questions and have it point at the same store console

Do you need to have an individual answer for each individual question in the different ways that somebody might ask it?

Nope. You can have multiple questions all pointing to the same response

That I believe when you saw in December that was not available but that is available now and in fact when you create a bit of micro content if if you decide OK this topic you know is 200 paragraphs long but I want to highlight this summary topic at the very of the summary paragraph at the very top I want that summary paragraph, to be the micro content for this entire topic, you highlight that, you tell it make micro content part of that process is it said OK hey what should be the request be you’ll type something in and it will be added.

So at the moment you create it there’s the request and the response you only get one request but then if you own that two-panel view that I mentioned earlier then you can go in and add multiple requests multiple questions that also support that same bit of micro content that we lifted from that summary paragraph.

Did that make sense?

That did, yes.

So that’s what’s happening within flow in terms of what’s given to the search you given to somebody that might be building a chat board with the search it’s already there for somebody who’s using Elasticsearch or it’s already there if you’re using the built-in search comes with Flare with the web-based content.

What gets given to somebody that might be wanting to build a chatbot? Do they get given HTML or XML or a variety of different options?

That was one of the tricky bits we had to figure out.

The problem is I’ve lost count I believe if you do the research there are something like 26 different active chatbots in use and as far as like completed available code you can put your hands on some of those are open sourced some of those are proprietary and for purchase, but almost all of them use a separate proprietary syntax and language.

Now one of the first thought we might do one of the very first chatbots out there they formalized an XML syntax an XML language did they called AIML the artificial intelligence markup language.

One of our first things we were going to do is let’s just produce AIML files, but then after doing some interviews with some people actively in the industry you know who are on the cutting edge, and then talking to some of our existing customers, well it turns out those who were using that language were already looking to replace it with something new anyways.

Or if people were brand new into the industry, they wanted use a newer chatbot than that older technology.

So that plan got scrapped, and so what we came up with it if we write the questions just as the simplest XML we can and then we write the responses as just straight-up Html5

That’s probably the easiest format for the developers to just transform to the syntax that they need, because if the developers are smart enough to you know pull off an entire chatbot system, transforming some raw XML and HTML5 should be trivially easy.

So that is the path that we took, but that does mean that to be able to feed a chatbot that would be need to be a transformation step.

Written one time in Flare.

There is a spellcheck?

Yeah I think this is the source as well if remember correctly.

There’s analytics tools to tell you where you help you write in a better way as well.

It’s all the fat functionality going to work on the content you’re writing in the editing environment for the micro content.

The spell check definitely yes, the thesaurus definitely yes, as far as the analysis of like reading comprehension and grade level I’ll put a “maybe” on the one.

If you’re sourcing the content from an existing topic well then absolutely because those tools were available on original topic

I’m going by memory here but from inside that dual pane editor I’m not sure if I could use the analytics on those little segments of text that’s the only one I’m not sure about there’s a good chance it does work it’s just not something I personally have tried so I’m not going to promise that here you know on a live podcast

That’s fine. I mean, most of the time that I’ve seen the analytic side of Flare use this to chunk links that are going to topics that have been deleted or or need to be fixed so and that’s going to be less relevant in this particular situation. But it’s more things like spell checking and the thesaurus and the readability and variables as well you mentioned.

I think you mentioned conditions like you mentioned variables as well. If you’ve got brand names that have changed, and you just want to flip them out between one or the other the way that you use variables for that that you, can you insert variables into these in micro content sections?


Or in for those who have used Flare in the past, if you’re familiar with our spell check interface, we can do a global project level spell check, or then you can facet it with a filter and say well no only check topics only check snippets there’s even a new filter just spell check micro content.

OK so that we you don’t have to do a whole big pass you literally can just spell check the micro content in one sitting if you want to.

MadCap also has the cloud-based management system and way of reviewing and editing

It’s the MadCap Authoring and Management system just released earlier this year.

So if you want to write the content and then get say a developer to review the content or subject matter experts does that functionality also extend into the reviewing capabilities of AMS as well if the content you’re using for micro content originated from an existing topic, that would, that reading process would be covered.

If the micro content was written just freehand in that question response editor, then that isn’t quite ready for the review process in the AMS in the cloud system yet in the officially the contributor system.

As of today MadCap Central has a built in just browser-based review and acceptance process for written topic based content for micro content, it would simply be reviewed as part of the viewing of the source topic.

So when it comes to how this content looks in such results what can you do to control how it looks is what capabilities do you have there?

Ah this is going to be a bit different than what you saw in December

A lot of this came from the beta community feedback

It also came from our own technical writing department feedback

Our developers love them

They decided that it was kind of a size fits all world and they gave us a fixed size panel that didn’t work

So we also have gone in and developed some new skin functionality so from an author’s perspective

You determine, OK what is the size of that snippet box above the search results

This also would be nice if you’re targeting a known audience and they’re not on high-definition monitors you know if they’re on smaller tablets you might want to reduce the size of that snippet box so it doesn’t overwhelm you know that tablet screen

You also have the option to have a drop-down widget as well so maybe most of your snippets will fit in a panel it’s four pixels tall but occasionally one doesn’t fit well you can have it automatically I’m a little drop-down widget a little drop arrow that will expand the size of that snippet box

So I believe when you saw in December it was just kind of a one-size-fits-all hey here’s the snippet box above search you now have a lot more control you can change its background colour so it’s different shading than the rest of the search results page you could put a coloured border around it to match your company branding

A lot more went into the presentation of that micro content since then. You’re only limited to having text in that micro content, or could you put in images or animated gifs to show the walkthrough of different steps?

I know that text works I know that static graphs work, your PNGs, your gifs.

I have seen an animated gif work

I do apologize I should have checked this before, I have not tried any live video but that that would be a bit well I meant more the animated gift

I meant more the animated gif type of thing because again you’re looking at as you say micro moments or something that’s very quick.

A full-length video yeah video would be probably heavy for that but yes animated gifs should work.

Using it to improve the search, using it to to give the capability of using that content in the in a chatbot, where else do you see its use the opportunity to use this micro content elsewhere in the future?

I think that’s one of the reasons there’s so much buzz about micro content as a concept.

Normally when something new gets added to piece of software it’s pretty much OK what do you see oh that’s all it does right now with micro content right out of the box, we can make search better and it’s very easy to transform and defeating these chatbots.

So right away that’s some new functionality, but I think the really powerful bit is when you think of all of the assistive devices these days.

You know I mentioned my Samsung phone and the little widgets built into its Home screen.

You think about Alexa type devices Bixby devices, Cortana devices, nobody programs these things to really talk the way they do.

They’re just reading micro content that they are scraping from other sports and information.

In fact I mentioned that big conference I just came back from India. I was actually surprised how many authors were fearful of things like chatbots, because they’re going to take technical writing jobs and I had to explain to these people these chatbots aren’t that smart.

Somebody has to write the text that becomes the brain of that chatbots system.

So we may not be writing a topics per se.

We might be writing dialogues now instead but somebody still has to do that writing, and I guess I’m getting long winded here.

I’m kind of more excited about the whole Internet of Things possibility.

Imagine being the right content where you can identify the most critical bits and then any other system in the world.

If your content is public, it’s able to scrape those bits and use them in new ways

So I think there’s a lot of opportunity there that we haven’t even seen yet, but that’s also you have to be careful.

I’m kind of the crazy mad scientist one inside the company as well.

I think when the buzzword that I’ve come across is “synthetic content”, so you’re taking bits of information from your repository and then building a page with the answer somebody wants synthesizing it and this gives you the opportunity to keep everything in one place all through it well and then leave it to developers to take that content and publish it in different formats shapes.

Absolutely in different situations

I had a question about when we like you to see it and it’s you’ve answered that – that will be in April

April or sooner, less sooner,

Right and also if they want to see you at the MadWorld conference in San Diego in April so you’ll present on this, there’s still space is left.

We still have I believe that hotels are getting a little bit tight but they’re still possible and I think we have a few dozen seats left to sell ,so there is it’s still possible to get in.

I’m actually doing this subject twice

Once I’m doing as a live presentation where I’m covering much of what we talked about here, but in a much kinder a deeper level with some actual live examples

But then I’m also doing a workshop

Now that’s going to be more limited to certain folks but if people wanted to bring their laptop bring their actual existing project we’re going to do a workshop where we create some micro content live right there in the room for those that want that deeper dive and again I don’t want to over speak this is not an official bit of functionality, but one of the things I think has a lot of potential is using micro content for things like context-sensitive help and embedded help in a simpler easier way than we’ve done it in the past.

Nothing in this upcoming release to make that easier, but that might be one of those phase two type items we talked about earlier, because the whole idea of micro content is content that is easy to repurpose so things like tooltips.

You know any of that little dynamic text just lends itself to micro content, but we’ve done a podcast to that on the Cherryleaf podcast before.

And one of the topics we’ve discussed is the situation where help is moved into the user interface.

So next to a field there might be a little bit of information that tells you how to fill in this that field, or that aspect. And at the moment one of the challenges is that that functionality isn’t within your three tools – that’s done separately.

It started with in the development environment of the application itself, for example or other situations. So this is one area where we’ve talked about the potential for using micro content in the future. So it’s interesting to see that that may be another application for this at some point in the future.

I shall say thank you, Mike.

and if people want to know more about Flare, or if they want to contact you what’s the best way to do thanks probably the best way is just to reach out to our website if you’re more interested in product information if you’re more interested in just learning more about the AMS, the authoring and management system everything is listed up on the website normally.

I would be happy to give up my direct contact information but I’m about to go into my North American springtime tunnel, where I’m doing training class trade show training class training class trade.

So I’m going to be a bit out of pocket for the next yeah probably eight to ten weeks or so.

The best route is just probably going through the website and reaching out to support or reaching out to cover care.

And the website is www.madcapsoftware.com, if I remember correctly.

Correct sir

Mike, thank you for that, that was really interesting.

My pleasure. Thank you for having me.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.