Inside Tech Comm with Zohra Mutabanna

S5E7 Enhancing Tech Writing Workflows with Markdown and AI with Christopher Ward

July 10, 2024 Zohra Mutabanna Season 5 Episode 7
S5E7 Enhancing Tech Writing Workflows with Markdown and AI with Christopher Ward
Inside Tech Comm with Zohra Mutabanna
More Info
Inside Tech Comm with Zohra Mutabanna
S5E7 Enhancing Tech Writing Workflows with Markdown and AI with Christopher Ward
Jul 10, 2024 Season 5 Episode 7
Zohra Mutabanna

Are traditional documentation formats holding you back?

Join us as Christopher Ward offers a unique perspective on the future of technical communication. Discover how Markdown, with its straightforward syntax and open nature, can revolutionize the way technical writers and subject matter experts collaborate. Markdown simplifies collaboration by separating content from style, bridges the gap with developers, and aligns content creation with business goals. 

We also discussed the profound impact of artificial intelligence and generative AI on the field, underscoring the pivotal role that technical writers play in developing and enhancing AI models while recognizing the limitations of AI-generated content and the irreplaceable value that human technical writers bring to the table.
 
Tune in for actionable insights and strategies to elevate your technical communication game.

Markdown Demo

Demo of the technical writing process using Markdown at 39:38.

Resources

Guest Bio

Christopher Ward is a dynamic professional with a diverse background spanning military intelligence, corporate sales, and strategic marketing. Education has always been a cornerstone of Christopher's journey. Graduating Magna Cum Laude with a Bachelor of Science in Telecommunications Management from DeVry University, he demonstrated a commitment to academic excellence and a thirst for knowledge.

Christopher is a certified expert in Google Analytics, having earned certifications for both basic and advanced concepts. His proficiency in data analysis and digital marketing strategies has been instrumental in shaping successful campaigns and optimizing organizational performance. 

A prolific writer and presenter, Christopher has contributed articles to various Technical Documentation Magazines and has graced stages across the United States and Europe. With over 15 years in TechComm and 20 years as a business analyst, he brings a wealth of experience and insights to every endeavor. You can contact Christopher at christopher@webworks.com.

Christopher is presenting at Lavacon. Use the discount code (Ward24), to get a $200 discount

Show Credits

Intro and outro music - Az
Audio engineer - RJ Basilio

Show Notes Transcript Chapter Markers

Are traditional documentation formats holding you back?

Join us as Christopher Ward offers a unique perspective on the future of technical communication. Discover how Markdown, with its straightforward syntax and open nature, can revolutionize the way technical writers and subject matter experts collaborate. Markdown simplifies collaboration by separating content from style, bridges the gap with developers, and aligns content creation with business goals. 

We also discussed the profound impact of artificial intelligence and generative AI on the field, underscoring the pivotal role that technical writers play in developing and enhancing AI models while recognizing the limitations of AI-generated content and the irreplaceable value that human technical writers bring to the table.
 
Tune in for actionable insights and strategies to elevate your technical communication game.

Markdown Demo

Demo of the technical writing process using Markdown at 39:38.

Resources

Guest Bio

Christopher Ward is a dynamic professional with a diverse background spanning military intelligence, corporate sales, and strategic marketing. Education has always been a cornerstone of Christopher's journey. Graduating Magna Cum Laude with a Bachelor of Science in Telecommunications Management from DeVry University, he demonstrated a commitment to academic excellence and a thirst for knowledge.

Christopher is a certified expert in Google Analytics, having earned certifications for both basic and advanced concepts. His proficiency in data analysis and digital marketing strategies has been instrumental in shaping successful campaigns and optimizing organizational performance. 

A prolific writer and presenter, Christopher has contributed articles to various Technical Documentation Magazines and has graced stages across the United States and Europe. With over 15 years in TechComm and 20 years as a business analyst, he brings a wealth of experience and insights to every endeavor. You can contact Christopher at christopher@webworks.com.

Christopher is presenting at Lavacon. Use the discount code (Ward24), to get a $200 discount

Show Credits

Intro and outro music - Az
Audio engineer - RJ Basilio

Zohra Mutabanna:

Hello folks, welcome to Season 5 of Inside Tech Calm with Zahra Murabana. This season, we are focusing on tools, tips and strategies to elevate your craft. Let's dive right in. Hello listeners, welcome to another episode of Inside Techcom with Zohra Murabana. Today I have with me Christopher Ward.

Zohra Mutabanna:

Christopher Ward is a highly experienced professional with a background in military intelligence, corporate sales and strategic marketing. He graduated magna cum laude with a Bachelor of Science in Telecommunications Management from DeVry University and holds advanced certifications in Google Analytics. His career highlights include winning the Top Gun Sales Award at Dell, serving as VP of Sales and Marketing at WebWorks and contributing to TechCom for over 15 years. He also brings expertise in data analysis, digital marketing and business strategy. Now Christopher Ward has an impressive background and this is what I have gleaned.

Zohra Mutabanna:

And this is a very condensed version of my introduction for Christopher and, if I may say so, I attended his Google Analytics workshop several years ago that the Society for Technical Communication, the Lone Star chapter, was organizing in Dallas, and I was floored. I learned some amazing tips. I am not a data analytics person, but Christopher just distilled it down for me. So I've known Christopher for a while, but this is my first opportunity welcoming him to my show. He has put in a tremendous amount of effort to bring great content to us and just prepared me to ask some great questions. With that, christopher, welcome to my show. It is an honor to have you.

Christopher Ward:

Well, thank you. It's an honor to be here and I am so excited I cannot, honestly, I cannot think of anywhere else I would want to be or doing anything else right now other than having this conversation with you. Thank you for having me here.

Zohra Mutabanna:

Thank you, christopher. It's a Friday evening and Christopher has taken out the time to spend this evening with us, so thank you again, christopher.

Christopher Ward:

Absolutely.

Zohra Mutabanna:

Now I have given a brief introduction about yourself In your own words. Please share what you would like to share.

Christopher Ward:

Well, I guess, in my own words, I've always been an analyst by trade. I mean, that's where I like to live and it's what makes me happy, and I like to look at things, solve problems. But, more importantly, I'm one of those people that fortunately, I have the ability to not only see the tree but I can see the forest as well. What I like to do is I really like to connect those images for people, especially if it benefits. I guess really that's what you said in sales terms and, forgive me, you're going to hear a lot of sales terms from me, just because that's my language but just really the best ways to benefit the customer. Because from a sales point of view, sales makes the world go round right. I mean, our economy would be flat if we didn't have it.

Christopher Ward:

And I've got to be honest that it never dawned on me until 15 years ago, when I got into this industry, that you know, somebody does write those manuals for us, somebody does write that technical documentation, you know, and I mean honestly, I never really gave it a thought. And then when I got into it and I saw what people were doing, I view it as probably one of the biggest missed opportunities in business back then and today you know. I mean, just what we can do with documentation is just incredible, and one of the reasons why I'm so excited about having this conversation with you right now is because I honestly feel we are on the cusp of creating what documentation is going to look like in the future. I mean, it's going to be totally different and I'm just excited about being a part of that.

Zohra Mutabanna:

I completely, completely agree with you, christopher. Our future is going to be a fascinating one, a challenging one, an interesting one, and we need to claim the ropes and really direct what our future is going to look like and participate in that future. But what you said, what I love the most, is you being in sales advocating for technical communicators. This is something that I'm very passionate about through my platform. That is my goal and objective to show how we bring value, how technical communicators bring value to the business, to any business, and with you validating that for me, and how we can bring meaningful impact to businesses with what we're going to talk about today.

Zohra Mutabanna:

It's fantastic. I am equally super excited and I love your energy. I love that energy. It's transferring to me too.

Zohra Mutabanna:

Now, for our audience who are listening in, we have Christopher, who's going to talk about how our future is going to shape up, especially with well, what else? Artificial intelligence, especially generative artificial intelligence. But today we are not going to be talking about AI. What we are going to talk about is how technical writers need to get involved in the development of these AI models that are coming into existence right now and that are going to evolve in the near term, especially in the next two to five years, and how Markdown is one way to impact our documentation workflow. And that's exactly what we are going to be talking about and that's what we're going to be diving into. So, christopher, my first question to you is why should technical professionals consider Markdown over other documentation formats? Because we have been using Word, pdf, xml and HTML. But before we dive into that big question, what I would like for you to do is for us to kind of distinguish what Markup is and what Markdown is.

Christopher Ward:

Okay, it's actually one that until I understood the difference between there, I really had the AI and Markdown thing wrong. I had the whole workflow wrong until I realized what the true definition is. And John Gruber. He's the one who developed Markdown, and so his original purpose behind Markdown was for writers. It was not for developers, it was for writers, and he was trying to come up with a markup language that would make it easy for writers to put content into an HTML format, and that sounds really simple, and that's exactly the way he wanted to keep it. He wanted to keep it very simple. So Markdown is actually a syntax, right? So when you say syntax, that means that you know you'll have your content in there, but then you have these markers in your content, right? So the markers in your content are keys for parsers or generators, something that's, you know, converting your current format into a different format and telling it what to do when it generates it into the new format. For an example, let's say you want a heading and you're converting a Markdown file into an HTML file. Well, in Markdown, that would be a simple hashtag in front of a sentence or in front of your heading, right? That hashtag would tell the parser that, hey, this is a heading, and when it generates the HTML, it will generate that heading with the style and information that's been predetermined. These are what mark-up languages were designed to do.

Christopher Ward:

John Gruber, though, wanted to keep it simple, because one of the things that Gruber did is that he's heavily involved in software development and coding, and the big thing about software developers is that they never want to take their hands off the keyboard. That slows them down, right, I mean, they hate mouse, they don't like to use them, right, and so, you know, everything that they do is command line interface or something along those lines. So, you know, gruber didn't realize is what he was doing is that he was developing the perfect tool for code developers to put documentation into their code, right, and that's how that Markdown came into existence. Now, I've never asked John Gruber this, so I don't know if this is for certain, but since it is a markup language and he was trying to keep it simple, I think that's why he gave it the name Markdown, you know, because his whole premise was hey, we need to keep it simple so people can move forward.

Christopher Ward:

I think what it does for us, and something that we need to recognize as technical writers, because this is going to be the whole thing for us. Is that we need to? Or when we at WebWorks started thinking about this, we were thinking about okay, it's a collaboration environment out there now, right, I mean, when you talk to an SME, now you really need their collaboration because, let's face it, software tools are getting more complicated. They're not getting less complicated. Not only are they getting more complicated, they are focused more on specific tasks, right? So now you can have a large system like a Microsoft Office or you know, or Linux or something like that, so an operating system can be large and perform a lot of tasks.

Christopher Ward:

And, believe it or not, it's really tough to find documentation in this stuff you know, but it's designed just to sit there and work right and notice that you're not really concerned about what's happening in the computer, in the hardware. You're just more concerned about the programs and applications that you have on it. You want to make sure that they work right. Well, we blew that out the water with the internet and then we started moving everything to mobile devices and you know, we started walking around and it's like now, all of a sudden we're going well, what can my device do? Right, because I mean we're getting. I mean you've seen all the blurbs about how, like you know, today's modern mobile phone has more processing power in it than the shovel that went to the moon, does you know? So we're really getting into an environment where there's a lot that we can do just with the devices that we carry in our pockets right.

Christopher Ward:

So it's like you start thinking to yourself okay, we have to have documentation on this stuff yourself. Okay, we have to have documentation on this stuff. No longer can we live in a world where we can go without documentation, you know, or have user generated content, right. So it becomes to a point where now it's like okay, we have to talk to our SMEs experts, find out what they know, craft that into a message and then deliver it to our customers. And you know, we started thinking to ourselves what's the best way to do that?

Zohra Mutabanna:

Got it. I think that's a great case for why we're going to be talking about Markdown. I think you covered that beautifully. We are working in a collaborative environment and our technical writers, until probably recently or even today, may believe that we work in silos, but that's not the true case. We are working in collaborative environments, complicated environments, and we want to make sure that we are aligning with the dev processes so that we can create content and impactful content for continuous delivery. And what better than Markdown? Because I have used Word, pdf, xml and HTML, but when I'm creating documents using Markdown, there's definitely a quicker turnaround. Why? Because my dev, I'm working in their environment and the Docs as Code framework allows me to engage with them and just there are many benefits to it and, of course, those benefits are what we're going to be diving into. So why should technical professionals consider Markdown? I think we've covered that with what you had to share and also what the differences between Markup and Markdown, so that was beneficial to me. So thank you, christopher.

Christopher Ward:

Oh, absolutely.

Zohra Mutabanna:

You did touch upon how Markdown simplicity enhances collaboration among team members, but I want you to speak a little more about that, especially when we are going to be working with AI tools.

Christopher Ward:

Okay, so think of it this way. As you said earlier, you know we thought we worked in silos and we actually did there for a while. We worked in silos and I mean that was helpful. It helped us get along and complete our task. But then you know, we had this technology boom, and I'm not talking about technology as far as Markdown and AI. Markdown has been around for a very long time. Ai has been around for a very long time. Right, we just recently have had this burst of AI energy, I'm going to call it and so you know, with that energy, it's like okay, what do we do with this? Good example and you and I have talked about this several times is that one good example of AI is Watson. Ibm developed Watson. I mean Watson was so proficient at what it did it was able to beat two humans on Jeopardy right.

Christopher Ward:

So that was pretty impressive. But once they did that, then IBM really had a hard time trying to sell that product and trying to figure out, okay, where does this fit in today's world? Right? So they were just kind of ahead of their time. I mean, right now Watson is being very successful in the medical field as far as, like examining cases, helping diagnostics, medical diagnostics, and they do that because it is so fast at going through cases that they can just feed some symptoms into it and then it can go through these cases and come up with a diagnosis for you very quickly.

Christopher Ward:

Of course, it has to be checked by humans, right? So one of the reasons why technical writers need to figure out or need to look at Markdown is because we are at a point where in our world, in our environment, as technical writers, we have to separate content and style. In our environment, as technical writers, we have to separate content and style. We have to get those two separate, and it's why we need to do that, is because that will allow us to have a conversation with these other departments, because, if you think about it, as we're sitting here, as you and I are sitting here talking now, we really don't care about font size, we don't care about what's bold, we don't care about how my table of margins are lining up. You know things like that.

Christopher Ward:

Now, when it comes to delivering a message to a specific audience, we'll be very concerned about Right. We want to make sure that information transfers over Right. So that's why the new workflow for technical writers, and the way I envision it in the future, is that it's going to be information from your subject matter experts. Like I said before I'm probably going to say this a couple more times during this interview but information from your subject matter experts on a conversational level, right. And the best way to do that is that you can either do that, I mean, think of it this way what was one form, one medium that you and I used to have this conversation to build up to this interview?

Zohra Mutabanna:

The email.

Christopher Ward:

Email, exactly right. Well, that's what Markdown is. Markdown is kind of like having an email conversation back and forth Very simple, very quick, so that actually speeds up your time. Not only does it speed up your time for you to get the information from your SMEs, it's also going to encourage them to contribute and to collaborate right.

Christopher Ward:

Because, I mean, I'm sure there are people in your audience right now have already experienced this. Put FrameMaker in front of a code developer and they're just going to look at you and laugh. They're not going to want to mess with that, right, you know? And guess what? That's what they're going to have to use. They're going to have to pick up that mouse and start looking through menus, because things like FrameMaker and Word I mean those have an integrated styling at the point of creation.

Christopher Ward:

And that's what's slowing us down as technical writers. I mean, we've tried think of the things that we've tried We've tried an agile workflow. That was really, really tough for us because, I mean, they were putting out bug fixes quicker than we could actually keep up with the content. We were having a really hard time. I mean, how do we measure that? How do we measure that? Okay, this bug fix justifies a change in our documentation or change in our content. How do we know that without actually looking at it and talking to the subject matter expert? And when we do that, we sit there and we say, okay, can you guys communicate in this authoring tool framework that I have? And then the owner said, no, I'm not even going to look at that and it's like, okay, I'll create a PDF for you and I'll send it to you. So you send a PDF to somebody and they look at it and they mark it up.

Christopher Ward:

Well, you've got six or seven subject matter experts. They're all contributing to that PDF. Now you've got this one technical writer that is supposed to take the combination of what those seven SMEs sent to you and put it together in one single document that still has to be reviewed and approved, right? Do you think that those seven SME experts are waiting for your document to be approved? They've got a job. Their job is coding, right. They're getting back to their job, which is what they feel is well, it is approved, right. And then also, too, you're looking at, they also have no concept. And this is not a criticism, this is just life. This is just the way it is. Code developers have no concept about information, architect or taxonomies, none. They don't know anything about content, reuse and different things like conditional text.

Christopher Ward:

They wouldn't know what conditional text is and, to tell you the truth, when it comes to topic alias markers, all they're really interested is, in the spot of URL, what you're using to get them there so that they can code that into the button that the user's pushing to get to that topic. So I mean that stuff really doesn't. It's not that it doesn't interest them, it's just that, hey look, I've got something to do. I've got to develop this feature in our product so our customer has a good experience and I can meet their needs. And then you've got to sit there and say as a technical writer okay, what's my audience? What's the best way to describe this feature so they can be successful with it? That's basically the elements of what we're doing. So when we start with Markdown, we have this conversation. Now we're speeding up the process so we can get to the point where we can deliver that message to the users, and then you know we can do it all through collaboration.

Zohra Mutabanna:

Yeah, does that make sense? Oh, absolutely All of that makes sense. In fact, I would agree with you on the review and feedback cycle, where things do slow down, especially when I'm using anything other than Markdown. When I'm creating content in the Docs as Code framework, I'm using Markdown and the feedback loop is quicker, a lot quicker. It's a lot quicker, there's better engagement, there's better quality feedback as well.

Christopher Ward:

Right.

Zohra Mutabanna:

Right and I think also it encourages SMEs, especially my developers, to participate because they feel part of the process. They don't feel excluded.

Christopher Ward:

Right.

Zohra Mutabanna:

It also kind of empowers technical writers, because now we are talking in the language of our SMEs.

Christopher Ward:

Right To tell you the truth, we've always been talking about language, right, I mean code developers and technical writers. You've always been talking about language. It's just the code developers. If you look at it, one of the reasons why Markdown was so popular amongst code developers is because code developers had a very specific audience, that they were writing to other developers, so it's very natural for them to write it into a readme file and then just pass along to other developers, right? Technical writers have to understand the specific audience that a business is catering to. And then they have to and I promise you, in every business, it's going to be more than one audience. From a sales perspective, we're not only looking at current users and current customers. We're looking at new users and new customers. How can we get them into the fold?

Christopher Ward:

Dr Spinozzi, a couple of years ago, wrote a paper on how marketing is losing its influence, you know, and so he was looking for a way to to change this. Well, more companies started putting their documentation on the internet. More prospective buyers was looking at that documentation, because it's not that they ignored the marketing, they just didn't trust it. But documentation is a trusted form. I mean, how great is that? Right, you know. So I mean. That's why it's going to be an essential part of not only just growing a business, but keeping it healthy, keeping it moving.

Zohra Mutabanna:

Absolutely, and you also talked about information, architecture and taxonomy and all these things that we have in our toolbox that we can leverage with Markdown in a simplified way.

Christopher Ward:

Absolutely, and in fact, to tell you the truth, that's where the exciting part of AI comes in play and it starts looking at. I mean, that's another reason why technical writers need to consider and look at Markdown, because Markdown now granted AI models can read PDFs to a point right now. Now, granted, AI models can read PDFs to a point right now. We've discovered that AI models they have a hard time with PDFs that are dual column, you know, and almost triple column is almost just useless to them. But so if you had a stripped down kind of, we'll call it confused, because if you put a really in-depth FAQ sheet at the beginning of your documentation, it may find its answer there and not go past it. What they're trying to do now is they're trying to figure out how to solve this issue, because right now, AI models they're really good. I call them, and one of the things I think that we need to do in the industry along with this is that I call AI models just a very, very useful and helpful search tool right now. That's what they are right, and I mean they're very though they lose focus easy, and that's the problem and the issue with models.

Christopher Ward:

I mean, that's when you start getting into things like prompting and prompt engineering, because, basically, this is what, as technical writers, something that we need to start looking at and start focusing on is that okay, how do we write a prompt for an AI model to return the results we want?

Christopher Ward:

That would be during the creation process. But you're also going to look at this and say, okay, how do I write to an AI model that is going to return the right results to one of my customers or one of my users, right? And then how do I do this without expecting my customers to be prompt engineers? You know, so it's like, okay, and that's what the AI industry is really trying to figure out right now, but they're just doing that right now to make it more marketable. I mean, there's a lot of stuff that AI can do right now that they're not focusing on, and one of the big areas I think they're missing where we need to get involved in the conversation is you know, how do you meet the needs of a technical writer through an AI model? You know. That's where we need to start talking. We need to start jumping in to this conversation.

Zohra Mutabanna:

One of the things that, as you were talking about the limitations of AI and how the potential future with AI is going to be we are kind of on that cusp and we need to kind of interject ourselves and influence what that is going to look like.

Christopher Ward:

Exactly.

Zohra Mutabanna:

Now, what I wanted to ask you was we've been talking about Markdown and I think Markdown definitely has a lot of advantages that it offers to technical writers, but in your opinion, why would the other formats not work?

Christopher Ward:

Collaboration is number one Hands down. You're going to get more participation with using a Markdown editor with simple syntax from your SMEs than any other device we have out there. Because, think about it, what do we have? We have FrameMaker. No developer's going to look at FrameMaker. Word. Nobody likes Word, you know, because it's just. I mean trying to create a style and have uniformity across documentation and Word is practically impossible. At least in FrameMaker we can create a style guide, right, but Word doesn't have that capability. Also about those two file formats is that they're proprietary, so in the raw form, ai is going to have a really hard time looking at that and reading that, and so it's not going to be as versatile as Markdown. Markdown is going to be able to be read by lots of models across the board. That gives you options as a technical writer and the company is to say, ok, okay, which model do I want to use? Right?

Christopher Ward:

so that's, you know those two and then you go into something DITA that that did is better because it's not a proprietary formant right, it's xml. A lot of things can read that, but you'll have to train an ai model on and how to read right in the hierarchy in the class, whereas AI models today they can automatically read Markdown, and so one of the things to where you can, or one of the things that we're excited about here at WebWorks is that we can see to where you can have the AI models the way they are now, it's very easy to incorporate them to cover the needs of technical writers with what they're going to use AI models with, which would include the information, architecture, taxonomy, conditional text, all that stuff and then you could actually include and start incorporating the styling information into the conversion phase. Like if I had a markdown document and I was going to HTML, then I would keep the conversation simple, simple syntax. I would take care of most of my technical writing needs through comments and then in those comments, my parser or my converter would be able to read and understand those comments and then produce the output that you would want. That's what we're looking for, right, because if you do it in that fashion, what we've done now is we've created a workflow that'll get you the exact results that you want talk to a variety of different audiences that can produce messages and deliver them over a variety of different mechanisms, mediums. So that's our ultimate goal, right? It's because we want to be able to deliver to any audience, anywhere, on any device, because that's how we make them successful with our devices, right? So that's in the working context. That's a customer that's already purchased from you.

Christopher Ward:

But think about this what about customers who haven't purchased yet? I mean some of the things that the Internet has done for those customers that you know we're really nobody's local anymore. I mean, I can see if I've got a product here in the United States, I can see what they're doing in Germany, what features they have there, and I can say you know what I like that better. I think I'm going to go after that product instead of this one here. You know, whereas now you've got all these creative minds and you're getting to see from different viewpoints and you're no longer in a box. It's wide open for people who are looking for prospective buyers. But if you don't have your documentation out there and if they can't read it, they have no idea what you're providing for. Well, now we can. Now we can put it out there. We can even work with marketing. There are a lot of AI tools out there right now. They're helping marketing, come up with some marketing material to hand out.

Christopher Ward:

But again, like I said, the reason why and you can look at it, I know there's been a lot of talk about hey, are AI tools going to replace technical writers, right? I mean, we've all heard that before. I can tell you right now no, not today, it's not going to happen, right? But I mean, technical writers will be responsible for getting or giving those models the focus they need to give you the output that you want. And see, you always need a technical writer because, I mean, think about how fast projects change and evolve.

Christopher Ward:

Ais don't have that focus. They're not going to be able to read documentation and say, okay, I see what you're doing here. Now we're going to have to tell them that and then we're going to have to lead them to say, okay, I want you to generate some topics for me, but this is what your focus is. Where your focus is going to be. I'm still going to have to edit that as a human and look at it, man, it's going put into my workflow Now. I'm pumping out to tons of different audiences, I'm speaking specifically to them across several different devices. I mean we've just opened the door, we've blown it wide open, right. I mean that's the excitement behind this and what we're going to be able to do.

Zohra Mutabanna:

Very true. I was thinking about the time to market with content you mentioned you're building trust with content, you're building trust with documentation and, if based on the workflow that you've shared, if we can accelerate that process where there's participation from our SMEs for quicker reviews, more accurate content and that content is readily available, especially with continuous integration that we aim to achieve for. And you also, I think, touched upon how, in agile sprints, technical communicators can sometimes be lagging behind. In my current role, I'm very fortunate to say that, with Docs as Code and even with the other tools that we are using, I'm able to do that continuous deployment. But I can see why it can be faster just because I have used Markdown and the quality of the reviews that we touched upon and the back and forth. It reduces that back and forth. There is a clear dialogue that's happening in the systems, within the systems that you want to create content in, rather than outside of those systems.

Christopher Ward:

Right, and also, too, I mean one of the things that I was talking about as far as, like, markdown documents can live in almost any environment.

Zohra Mutabanna:

Right.

Christopher Ward:

I mean, think about this. You don't have to go from your technical writing CMS system into a code developing system like GitHub With a lot of the authoring tools that we use now. We don't have that capability. You do have that capability with markdown. That markdown file document can live in both environments, Right Back to where you could. Actually that's where you could do your collaboration, you know, in that CMS system if you wanted to. So that's one of the good things about Markdown, and remember that's Markdown without any AI help at all or AI model. That's how the collaboration is so strong Just keeping it, just simply by taking away the styling information and having an actual conversation and putting the styling back into it later in the process. This is why, in our point of view at WebWorks, we feel Markdown is going to be the way to go. It's going to be the future of the document process. There's a lot of benefits to it over the editor file formats.

Zohra Mutabanna:

You mentioned the many benefits of Markdown and how it can impact our workflow and we've kind of touched upon the workflow five formats. You mentioned the many benefits of Markdown and how it can impact our workflow and we've kind of touched upon the workflow in parts. What I would love for you to do is kind of from beginning to end, just looking at that workflow. If you can, for the benefit of my listeners, sort of walk us through what that journey would be like with Markdown and how we can impact the AI models using Markdown. Just a walkthrough.

Christopher Ward:

Absolutely. So it would start with. I mean, as far as, like a technical writer, you want to be accurate but you want to make sure you can give all the information that you want to out there to that customer, that prospective customer or, as we said before, that prospective buyer, right? So in order to do that, you have to talk to SMEs and you have to get that information from them, especially when it comes to, like, a new feature or a new product, or even the base function of the product that you're developing. So to do that, you have to have that collaboration. That's how it would start. It would be a collaboration between that subject matter expert and the technical writer. And if we're starting from scratch let's say we're starting from absolute scratch that you know you're going into. You don't have any content, taxonomy in there just yet and you don't have any information, architecture just yet. You know, one of the things that you would start doing is that you'd have that collaboration and, as a technical writer, you would start building your documents, right? Well then you can start interjecting. You don't have to. You can do all this manually. Ai is just going to speed up the process, but it's then you can start interjecting. Ok, how do I build my taxonomy from this information that I'm pulling in? How do I do my information architect? Because you know, hopefully, if you're in a position to where your documentation isn't so large that you can manage this in the small set, because everybody knows documentation goes, never goes backwards, it always goes forwards and it always grows. So this is giving you the opportunity to put that in place.

Christopher Ward:

One of the difficult situations we're in as technical writers is that, man, if they're turning out product like that, we don't always have the time to put in a taxonomy or create a taxonomy or get that information architect. A lot of times we're having to catch up on the back end after it's grown so large that it's not just as simply as adding a category to the taxonomy. Is that we have so many categories out there. It's going to take a lot of labor, time and effort to get that taxonomy there. Because what does taxonomy do for us? Not only does it help the writer pulling information with content use and creating a TOC or whatever we're going to use to put out that content, it helps your user find what they need, right?

Christopher Ward:

I have a good friend that says nobody likes looking for their keys, but they love finding their keys. Customers are the exact same way. Right, that's what they want to do. They want to find that information. Well, that's what taxonomy helps us do. So they're important and with the information architecture that you have in there now, you're getting to, you know, content reuse, you're getting to version control, what needs to be updated, things along that nature. So that's all can be done manually in this process.

Christopher Ward:

But, man, if you interject AI in there, all of a sudden, you're getting the AI to do that for you. I mean, even today, we can, I mean, if you like, get into an AI model and just start typing around, ask the questions you know. I mean, like chat GPT is a great one to sit there and type a question hey, do you know what a content taxonomy is? And it will know what a content taxonomy is. But you have to say content taxonomy. You have to say content taxonomy, because if you say do you know what a taxonomy is, it's going to start with the original taxonomy and tell you about how it was originally used to categorize different species of birds and fish, and then you know.

Christopher Ward:

So that's that focus I'm talking about to where it loses that focus. To get back to your original question OK, so we would start with that information gathering process. We want to make sure that you have that down, or at least you know a stable foundation for it, so we can move forward into crafting a message. And, if you're looking at it, you can even break up your edit review process into a couple of different steps. Right, your edit review can be in this collaboration that you have with the SME. So you're making sure that you're getting the right, you have a good understanding of the information that they're giving you. And then, in the review process, you're probably going to be collaborating with other technical writers and you're going to say, okay, here's what I have for this message. You're going to actually be able to do that a lot faster in this workflow with the markdown file. Because, why? Because nobody's worried about style, nobody, right? We're all worried about the message.

Christopher Ward:

And that's where AI is right now. It doesn't have that focus right, and that's where commas, and that's where you know, grammatically, you get this stuff correct. That's what you're doing, that's what you're bringing to the table when you're crafting a message for AI. Because AI, as I said, those turning tests it's never passed one, you know. Because I mean, if you really go to the basis where AI first started, there were two ways that they started developing AI. One was just a question and answer method. Right, you would ask it a question, it would give you 10 answers and you would start telling it okay, number one and two are right. Three and four are way off base. Five is close. That's how they would teach it right.

Christopher Ward:

Then they started developing what they called the network or neural network type of AI interface, which we're trying to get in there. We're trying to get you know, we're giving it tons of information. We're trying to help it make those connections. You know, connect those dots and stuff, and we're getting better at that, but still we're having to help it connect those dots. It is not. Ai is not at a point yet where it can connect those dots by itself.

Christopher Ward:

I don't know how close they are to something like that, but I don't feel like they're very close. I really don't. I think that they get a lot of buzz out there about AI and stuff like that, so people will be interested in it, but honestly, I think they're at a point where they need a lot of help. This is why I'm excited that we're having this talk, because it's not like they don't want help from technical writers.

Christopher Ward:

I don't know if you remember when I first started, I like they don't want help from technical writers. There's just, I don't know if you remember when I first started, I said I didn't even realize until I got into the industry that somebody broke manuals, that somebody put this stuff out there. Everybody's kind of that way. You look at small business owners, almost none of them think about okay, how am I going to do the documentation? They start out and they say, okay, I'm going to put a PDF out there and that's going to be it. That is not going to make it anymore, because small business owners are going to get hit to the fact that with this simple workflow, I'm going to be able to put my message out there quickly. And then they're also going to get hit to the fact that, hey, I need a technical writer now to get in there and start helping me focus that AI so I can get the right message to my audience. Right, so I'm no longer entrapped by, you know, trying to nail that one or two big sales.

Christopher Ward:

That keeps me going for a while. Man, I can apply to everybody, which is essential because, like I said, everybody's a global market right now. I mean, that's what we're looking at. You got to get out there and you want to talk to people, and especially if you're in software development or something like that, with a quick download, especially the boom of SaaS applications right now, you know, I mean, all you have to do is host your solution and allow people access to it, and they can get it from anywhere in the world, just practically on any device. This is the stuff you're looking at. This is where you got to start thinking as a technical writer.

Zohra Mutabanna:

You're a technical writer. Slash sales professional right. Awesome, Awesome no-transcript.

Christopher Ward:

Or we have this other view, which is kind of delusional in the fact that we say, oh well, ai can't contribute to anything to what I do.

Christopher Ward:

We've got to stop with those views and we've got to look at the reality of it, you know, because I mean it's like I mean if all of a sudden, we, as technical writers, everybody forgot tomorrow, everybody forgot how to do their job and there was no more technical writers out there, there would still be AI modules out there, but they would just be producing unfocused, bad documentation. Or we need to give technical writers a mechanism to where they can become very familiar with AI. And I mean we've got. I mean there are free tools out there. Don't have to wait for the budget, right, there are free tools out there that have already taken markdown editors and incorporated AI into them. I mean I know we're long on time here, so that might be if your audience wants to have me back. That's what we could talk about is I could show those free tools out there and how people can use them, because some of them are really.

Christopher Ward:

Not only will they get you familiar with it, but they can actually teach you Markdown in the process and then you can work on typing the right prompts to get the results you want out of the AI component that's in there. You can also do things like load up documents. I mean, if you want to get into the paid services for some of these AI models, like, just an example, chatgpt 3.5 is the free version. It's now allowing you to create your own wizards. So basically you can create a wizard where you can upload your documentation and then you can ask it any question. And they've actually it's really a cool effect because it will go through your documentation and it will write a summary, but under that summary it's going to give you the areas in the documentation where it built that summary from, and then it's going to be the one that it the that it used the most, that it signs the top priority to. It'll be number one. So if the user wants to look into it or click on that and look at it and I see a little bit further into it they can. The way I see it is that they're doing that, so nobody really has to be a prompt engineer, you can ask a very generalized question.

Christopher Ward:

In our documentation I could say how do you create a heading in Markdown? And then our documentation would show you a heading, the top one right. There would be headings, because we have a section for how to create a heading in Markdown, but then we also have a section for how to create a heading in a table in Markdown. So now that user can look there and go oh well, that's what I'm trying to do. I'm trying to do I'm trying to create a heading and a table, not just a heading. So now I can click, now I can go directly to the place it wants to in the documentation without having to be too specific in the prompt that it was giving, and that's going to be really good for users who are looking for documentations to solve a problem. It's not going to be as useful for creating that documentation, because the documentation has to exist for the AR module to get that information back.

Zohra Mutabanna:

Very true. How about we at least have one?

Christopher Ward:

demo. Okay, I'll show you one that I kind of like. Actually, I'll show you and I'm just going to share my screen, so the one I'm sharing now. This is called Notion. Notion is kind of cool because this is the one that I was talking about as far as like, it gives you the ability this is documentation with the topics that I this is our documentation that I uploaded to this AI model. So, just to show you what I was talking about earlier, I can go in here. I can type this is the AI model, right? This is my simple text editor with Markdown in there. Now you can see here that it's giving me a preview. So, even though this file was a Markdown file, let me see if I can show you this too. I mean, what the heck? I might as well go all the way through it. So this is Markdown. Let's see Sporny. Publisher now.

Zohra Mutabanna:

So this is a Markdown editor.

Christopher Ward:

Yeah, well, actually this is Notepad++, it's a simple editor. Simple editor Got it Right and you can see here I can go to language and I can say Markdown pre-installed. I click on that and it's what that does for you is like this line under here in Markdown++ that's a title. I mean Markdown's simple syntax starts with just a heading, a heading one, a heading two, a heading three. We know that technical writers like chapter titles and titles so they can have a larger hierarchy or information architect, when they're putting documentation You're going to find code developers most of the time are only writing for one topic, so a heading one is typically all they need. You can also see here that this is a comment. In Markdown it's an include, so we're actually mapping topics into this document. So when it parses out the HTML it looks like a full document set. So this is what the original document looks like. This is the preview of it that this simple text editor at this program is giving me.

Zohra Mutabanna:

And what's this program called?

Christopher Ward:

This is the Notion.

Zohra Mutabanna:

Okay.

Christopher Ward:

Okay, you can see here it has a little trouble, like the image couldn't be loaded. That's because we did a path to the image. We like to keep our. Again, this is information architect. We keep our media resources different than the topics themselves and we use a link to put it in to the published output. So you're going to run into a few things like this, but what we're doing, or how we're using this, is that I've got all my content in there, so now I can start asking the AI some simple questions.

Christopher Ward:

So I say how do I create a heading in market. Simple question, right? Most users this is about the level that they're going to get at when they do a prompt for an AI tool, so it thinks about it. Now here's the thing. Since this is a tool, now this is on my desktop, so this is actually faster. I get a faster response than I would if I was using their SaaS tool. Now this is on my desktop, so this is actually faster. I get a faster response than I would if I was using their SaaS tool.

Christopher Ward:

I know speed is an element that we want to be concerned with when we're offering documentation to our users, but there are tons of ways to improve that if you're actually going to start using and incorporating it. So don't pay too much attention to that. What we're focusing on here is that you can see here to create a heading and markdown, use the hashtag symbol followed by a space, then your heading text. So it's telling me how to do it. But then also to give me some resources here. You know and like this is what I'm saying. Well, okay, this is where it pulled from. You can see it's telling me with the number one there, this is the top resource that it pulled this answer from. Does that make sense?

Zohra Mutabanna:

Yes, yes Okay.

Christopher Ward:

And so I'm going. Well, you know, I really want to talk about tables, so let's click on tables, and now it's telling me how to do it in a table, and it's got that information on the table and what I need to do. That's kind of taken away the need or necessity to have a very specific prompt or to focus this AI. Basically, this AI is saying okay, here's a simple answer to what you're asking. Did you want more information? Because here are the resources I used to gather those resources for you. This, though, you need to limit this. This is not an internet search to where I'm looking for every resource on the internet to tell me how to do a heading right. Too much information, it's going to go crazy. That's when you start hallucinating. So this, though, the way I limited the scope of the AI model, was to upload my documentation, and I said you're only searching through my documentation, so this is in the context of how it would work if you were content for a particular user.

Zohra Mutabanna:

This is a great example.

Christopher Ward:

Okay, and so this is one. Another one that I like down is this is Markdown. I like this one because, if you don't know anything about Markdown at all, this is the one I would suggest people to get started on, because, as you can see, it is literally a simple window to start typing into. This is like an email. It isn't quote unquote editor, but it's really a simple email. You can see here it says press forward slash for commands and space for AI, so I can do a forward slash here, and then you can see how it gives me a list of markdown things that I can do. Right, so here's my heading. Again it's telling me hashtag plus space. So very simplistic Text code quotes. These are the things that I would have to enter in to get this result. So, bulleted list. So if I wanted a bulleted list, I can press that, and now it's giving me an option to say you know, list item here.

Zohra Mutabanna:

So are these tools for free? Yes, they're all for free, they're all for free? Yes, so this is not something WebWorks proprietary.

Christopher Ward:

No, no, no, I can show you.

Christopher Ward:

I can show you what we do as well because, actually, to tell you the truth, you could get it for free from ours, our website also. Just download the trial version, because the trial version has Markdown sources. You can also do the Markdown plus plus, what we call Markdown plus plus and like, if you look at, like, if you go to our documentation here, in our documentation we have authoring source documents and so we have Markdown plus plus source documents, learning, markdown, learning plus plus, so you can use this as a guide, you can see if I go to learning Markdown. These are some very simple things that are already in the Markdown basic syntax, things that you want to do. How do you create a link? We've got that information for you right here. But if I go to Markdown plus plus, you can see these are things that we've added that you can do now with Markdown, so we can do aliases, markers. Conditional text file includes variables.

Zohra Mutabanna:

And this is available with regular Markdown right.

Christopher Ward:

Yes, that's the beauty of Markdown is that if you know the syntax, you've got it with your Markdown. But so don't look at it as a feature with Markdown. You need to look at it as a feature with my generator or my parser, only with ePublisher. Epublisher right now is the only tool that reads Markdown plus plus. So if I wanted to generate an output and this is our ePublisher tool I'll show you this real quick and I promise you this is not a, this is not a plug for ePublisher. I'm just kind of explaining how it works. So so you can see here my exploring the publisher. You can see this is that include that I was talking about, okay. Okay, if I explore the file, this is where I'm keeping my source documents and right now this is all local. If you go to our product cloud drafts this, this can happen the exact same way in the cloud as well. But if you see here I've got my topics here and these are all my topics. You know, if you look at like, the first topic I have in this include is learning Markdown. So if I go to my source documents, you can see here I have learning Markdown. That's that file. And if I open up that file. You can see this is even more. This is Markdown, basic syntax, right, that I have in here. Pretty much all I'm doing is that I'm bringing in, like this reference here, that's basic Markdown this line item here, or this list here, basic Markdown. So what's cool about it is that you can see here that I can do links or references in my list as well. So it's really cool. As you can see, I just have a dot, one dot here for each one of the line items Markdown. Any person will automatically add it, like the next one would be a two my generated output, the next one would be a three, things like that. So I don't have to worry about counts. I can just put the one point and the parser does it for me.

Christopher Ward:

Then when I do my output, you can see here I'm going from this right Learning, epublisher, markdown++ syntax, epublisher Express and one-click publishing including these topics, and then it's publishing out, my parser's publishing out and giving me it's incorporating those files into my final output. So when I'm actually generating my final output, I'm going to have, in this particular instance, I'm going to have an HTML document that has my full document set into it, right, and I'm doing that all through, it's going to be able to take this include and include it in the proper position. Not only will it include it in the proper position in my output, it'll also build it into my TOC and also builds into my search capabilities, you know. So I mean just by so you can have this, this authoring capability, in any simple text editor, like I use Notebook++.

Christopher Ward:

I know Markdown++ right and so I can. Actually, since I know it, I know how to do the includes and stuff. I mean we have documentation so you can learn it. But you can see here that this built that ePublisher. It got me all my topics in there. It got the TOC. Even my filtering I can filter out. You know my search filters, for when I'm searching for, you know, headers or something like that, I can sit there and say, okay, well, I want headings, I only want my headings in my exploring ePublisher so I can filter out my results. That way, all that's done and I've got a fully functional HTML output that has all these filters built in and then that I can run Google Analytics behind. I can put it somewhere and run Google Analytics behind it.

Zohra Mutabanna:

This is pretty much the end-to-end workflow that we talked about.

Christopher Ward:

Exactly and I'm doing it. You know I'm now. Of course I didn't go through the any of the edit review process and stuff like that, but basically that's what we're trying to do. We're trying to get from here to here, and I just did it using a Markdown. Not only did I use a Markdown document, I've got a lot of features in here that are technical writing, features that they need when they're trying to put that in, when they're trying to do their work. We can also have AI tools that can interject metadata for taxonomies, for information architect. They can either do it in a metadata form or they can do it in a commenting form. This is what you can now do with Markdown in a simple text editor. I'm still keeping this all very readable and I can do this all straight on my keyboard. I don't even have to touch my mouse at all In our particular product in our workflow.

Christopher Ward:

All the styling information is contained here in our product, right? And that's what we do is basically, we just create a stationery it's like style guide, and then we apply that style guide with publishing. If you don't have that capability, a lot of the parsers like in GitHub, things like that those parsers, they already have a predetermined or they allow the browser that you're viewing to determine what the styling is going to be. So you don't have any control over the styling that determine what the styling is going to be. So you don't have any control over the styling. That really I mean for edit review. That's it's nice.

Christopher Ward:

Where you'd run into troubles is that you know it's like okay, how do I really want to format my table? How do I really want to format my list? It really comes in to play if you're trying to put warnings or tips and tricks in there. But right now we have a parcel that can handle all that. We can do all that, but this is where the conversation needs to happen. This is why you and I are having this conversation. It's not to plug my product, even though we have the best one out there, but we need to have these conversations. We need to get onto sites like CommonMark, because right now, probably the biggest issue facing Markdown as a viable editing tool offering tool is that first of all, there is no Markdown standard. I mean, you've got Markdown that John Gruber developed years ago and then you've got a GitHub flavored Markdown, whereas some of the syntax in the GitHub flavored Markdown does not match the original basic syntax in the John Gruber.

Christopher Ward:

John Gruber wanted it like that because he gave his Markdown syntax the ability to read straight HTML if you wanted to type in straight HTML.

Christopher Ward:

Problem is, is you kind of get away from that readability because HTML has a lot more syntax to it than Markdown, you know. So these are the reasons why we say, okay, this is the reasons why we're going to do it this way and you know, this is why we put the documentation on our website. Like I said, to get to it, I just went to the website, wwwwebworkscom resources documentation and it's right there and you can read all the documentation about it and what we've done and we're continuing to develop it, because right now this is a local solution you can install on your desktop, but we're going to make it a SaaS solution, which I think that's where everybody's going to take this. You know that includes taxonomy, includes the information architect, things like that, and it's going to be especially helpful when it comes to when you want to generate output that has the chat ability from an AI mechanism. We, when you want to generate output that has the chat ability from an AI mechanism.

Zohra Mutabanna:

We're going to be able to provide that for you as well. I'm glad that we got to this demo so that our customers can get a flavor of what the workflow that we've been talking about looks like.

Christopher Ward:

I hope I was able to articulate clearly enough. If not, I'm always at webworkscom. My email address is christopher at webworkscom, so if they have questions, we can definitely follow up. I mean, I would encourage them to get in touch with you If they want another presentation to cover some more of the tools how to get more familiar with Markdown, how to get more familiar with that process. I'd love to come back and give a presentation on that as well.

Zohra Mutabanna:

I might just take you up on that and maybe we'll have round two.

Christopher Ward:

Absolutely. I might just take you up on that and maybe we'll have round two of the discussion that we've had.

Zohra Mutabanna:

Christopher, I really appreciate your time and everything that you've shared. I have learned more about Markdown and just how I can make myself more valuable to a business, and hopefully this is what my listeners will take away. But thank you for your time. Have a wonderful evening.

Christopher Ward:

Thank you for having me here. I really enjoyed this conversation and you have a wonderful evening as well.

Zohra Mutabanna:

Thank you. Subscribe to the podcast on your favorite app, such as Apple, spotify or YouTube Music. For the latest on my show, follow me on LinkedIn or visit me at wwwinsidetechcomshow. Catch you soon on another episode.

Markdown for Technical Writers
Improving Technical Writing Workflow With Markdown
Maximizing Technical Documentation With Markdown
Leveraging AI in Technical Writing
Markdown Editors and AI Integration
Maximizing Markdown Features for Technical Writing