Bob DuCharme, an experienced technical writer and author talks about writing documentation for software products. In this episode we discuss the various types of documentation that one creates for software products. Host Nikhil Krishna spoke with Bob in depth about the difference between these types of documentation and the audiences they target; importance of using proper grammar and clarity in writing good documentation that people want to read; other forms of documentation (images, video and audio); challenges of maintaining and updating documentation; keeping documentation in sync with products; toolchains for building documentation; history of software documentation tooling and standards.
This episode sponsored by OpenZiti.
Show Notes
Related Links
- Episode 31: Agile Documentation
- Episode 426: Philip Kiely on Writing for Software Developers
- The Elements of Style
- Bob DuCharme’s Blog
- Blog articles on documenting software on Bob DuCharme’s
- Software Documentation: The Practitioners’ Perspective
- Technical Writing : CSDL | IEEE Computer Society
Transcript
Transcript brought to you by IEEE Software magazine.
This transcript was automatically generated. To suggest improvements in the text, please contact [email protected] and include the episode number and URL.
Nikhil Krishna 00:01:05 Hello and welcome to Software Engineering Radio. I’m Nikhil and I’m a new host on Software Engineering Radio, and I have the pleasure to introduce Bob DuCharme. Bob is an accomplished writer, software engineer, and a data architect who has been involved with the semantic web since 2002. Bob is an author who has written books for O’Reilly, Manning, and Prentice-Hall — specifically, Learning SPARQL, XSLT Quickly, and The Annotated Specification and SGML CD for Prentice-Hall. He’s also written in magazines, so he has written for the Modalities magazine, O’Reilly Networks, XML.com, Dr. Dobbs channel, and even IBM technical books. He is currently a technical writer at Katana Graph, makers of a high-performance distributed graph database, and is based in Charlottesville, Virginia, and has five books and nearly 100 online and print articles about IT. Bob is proud to have never used the word “functionality” in any of them. Bob, is there anything in your bio that I might’ve missed or that you would like to add?
Bob Ducharme 00:02:16 I think you’ve got the key things. I mean, I’ve sort of gone back and forth between software development — solution architect is always such a vague term, but you know, helping customers figure out what they’re going to do — and writing it up. So sometimes more coding, but right now I’m happy to be in a position where I’m pretty much a full-time writer.
Nikhil Krishna 00:02:35 Awesome. To give listeners a little bit of an overview on what they’re going to do in this particular episode, we’re talking about creating technical documentation. So, obviously there are various types of documentation and you have a role as a technical writer right now in Katana Graph. So perhaps we should start with a little bit about the technical writer role itself. So, the first question would be, why do we need this role? Why is the technical writer necessary for a software organization?
Bob Ducharme 00:03:06 Typically, when people get a product, they want to know how to use it. And there are brilliant programmers out there who know their favorite languages inside out and all the cool things you can do and how to do them efficiently. But those developers might not know how to explain the end user usage of those products to people who are new to it. So, explaining to people, figuring out what they’re going to want to look up and how to do these things, that’s really the tech writer’s job: you know, to write the user manual, basically, the user manual or/and reference guide and other things like that, which we can talk about have overlapping responsibilities. But people will get a software product, they want to know how to use it, so the tech writer is the person who explains how to use it.
Nikhil Krishna 00:03:50 Cool. So just to dig in a little bit, what are the specialized skills? So, what does the technical writer bring to the job that maybe a software engineer with an English speaking background cannot do?
Bob Ducharme 00:04:03 Well, typically to enjoy writing. I mean, a lot of people just don’t like it; they view it as an awful chore. Maybe somebody writes on the side or has a blog or something like that, but you need to be able to talk and communicate with on one hand the end users and on the other hand with software developers to understand the technical parts. If a developer has a new feature and says, here’s what it does, and that’s not clear, the technical writer has to be able to ask the right questions to say, ‘I get this part and this part, but this part here, how does that work?’ They need to sort of interview them to find out the information necessary, to then explain it to people who are new to the product who don’t have that technical background. So, the communication skill is going in two directions. One, to the end-user and two to the more technical people, the developers.
Nikhil Krishna 00:04:50 So, does that mean that the technical writer needs to have a software engineering background because if he’s talking to software developers about technical topics, does that mean that you need to have that same language of same vocabulary to be able to understand?
Bob Ducharme 00:05:08 It helps. I do have, since I first became a technical writer, I along the way did get a master’s in computer science. And that has helped me a lot to understand the technical talk and also to help sort out actual technical terms from buzzwords, which is another thing, because, you know, you hear these words getting thrown round. Some of them have specific meanings, some of them get misused. So, I’ve often joked in some places that I’ve worked at having a master’s in computer science helps me to talk to the PhDs. And then translate what they’re saying to regular people. So it helps, but it’s not necessarily, especially if the product is — some products will have end users who are non-technical. If it’s a phone app to help track something, but some products will have technical end users, especially if you’re going to be writing about, an API or something like that. The ability to communicate with the developers becomes more and more important then the more technical audience is.
Nikhil Krishna 00:06:05 Awesome. So again, just to kind of elaborate a little bit on that. So what kind of documentation, technical writer typically focus on? Do they actually create design or architecture documents? Or is it more like user-facing documentation, like manuals and installations? Is that, I guess a function of what kind of software project you are writing documentation for? Or is this something that as a standard is always going to be written by a technical writer?
Bob Ducharme 00:06:38 I would say that you’re, if someone has a technical writer role there, their primary job is to write user-facing documentation. These sort of architecture diagrams and stuff, it’s interesting to see those, and those are good background when they’re developing. But if a company is going to budget to have a tech writer that is to have someone who creates that part of the product. The part of the product that helps end users get up and running. And there’s three basic types of user documentation. And when I first started this, it was back in the day when there were printed documentation. We would make three separate volumes for this at the places where I worked. The first would be a reference guide. A reference guide should explain basically everything somebody sees in the product, every icon, every menu choice. If they look at something and think, what good is that?
Bob Ducharme 00:07:20 What’s that for? They should be able to quickly find it and look it up and see what it does. And then apart from the reference guide, the other big one would be the user guide. A user guide is arranged more in terms of the tasks that the end user wants to do. The user guide is really aimed at someone who doesn’t know the product. So, for example, if it’s a database program, it would say how to create a new database, how to put data in there, how to edit it. You’d mentioned, I wrote a book called “XSLT Quickly” for Manning, which was about the XSLT language for manipulating XML. And I had come from a background with SGML before that; XML is basically a simpler version of SGML. And my work with SGML enabled me to, when I wrote the outline for the XSLT book, before I even knew how to write any XSLT, I was still able to write a user guide outline because I knew what the tasks people had to do were: Create new elements, rename elements, convert elements to attributes and back and forth, delete, rename.
Bob Ducharme 00:08:17 I knew what the basic tasks were, so that I could create an outline that said things like, How to Create Elements, How to Delete Elements, How to Rename Attributes, and so forth. So, when someone’s looking at a user guide, they want to see the names of the tasks. The user guide shouldn’t be talking in the technical language, or at least the Table of Contents should not be talking in the technical language of the product. It should be talking in terms of the tasks that users want to get done. And that’s not always easy because you have to, maybe work with marketing and work with some of the UI developers to find out, to understand the users, what are they trying to do with this product? What are the various things? How do those things fit together? You really have to get inside the user’s head, so you can then explain here’s how to do this. Here’s how to do this. And that brings me to the third category of documentation along with reference guide and user guides would be, I might call it a quick start or getting started, but a tutorial. Sometimes I’ve seen getting started to cover installation as well, but a tutorial for someone who’s never used the product, which I consider almost like a demo, like giving a demo to yourself, you know: step one, click here, step two, click here on this comes up. That’s for this great reason, because to sort of show off the cool parts of the product, maybe even it’s in a way, similar to what someone giving a demo in front of a conference might do. To go through 10 or 15 steps to show the cool parts of the product. The tutorial, I think, is something where a script \someone can give that demo to themselves and see how cool the product is and how to do the basic things. So those, I guess, would be the three categories, reference guide, user guide, and a quick start tutorial.
Nikhil Krishna 00:09:50 So as a software developer, if I’m interested in this field, what are the skills I need to cultivate? Maybe are there some simple guidelines that as developers, we can follow to improve our documentation for maybe our side project? Or maybe even if it’s not our project and we’ve been asked to do some documentation, what are some simple guidelines or things that we can do to make sure that we’re writing good technical documentation?
Bob Ducharme 00:10:23 And here’s something I’m probably going to say a lot: there are a lot of analogies to writing the software itself. So, for example, with documentation, if the software was developed from a well-organized set of requirements, those requirements are going to be very useful to you. You know, there’s this list saying customers should be able to do this, customers should be able to do this, customer should be able to do this. So, if you have some well-written requirements, that’s a great place to start. Here’s how to do this, here’s how to do this. Other things include, I always like to think of two classes of reviewers. When you write, explaining something, you want to show it to, of course, a developer or someone to make sure that you explained it correctly, that you didn’t get anything wrong. But you also want to, what I call a target audience reviewer — someone who doesn’t know the product but has some interest in learning the product; have them read what you wrote and see, could they follow along? Did your explanation work for them? And if not, where? So those two kinds of reviewers I think, are important to keep in mind when you’re developing something.
Nikhil Krishna 00:11:26 Okay. So, are there any simple things that we can do in terms of the language itself? So maybe, this is a good way of putting, so is grammatical accuracy absolutely write to? Or is it okay to say, okay as long as I’m technically accurate some grammatical issue are fine, it’s not that strong. What do you think?
Bob Ducharme 00:11:57 Well, I mean grammar it’s not like, when you’re writing code and if you forgot a semi-colon the whole thing’s not going to compile, right? It’ll still be there. But if the grammar is bad, it’s probably going to be harder to understand. You know, if you have a plural subject with a singular verb, people reading it, aren’t going to stop and go back and it’s going to be harder to follow. So, I think grammatical accuracy, simple things like that and punctuation, these things I think are important. It’s going to be harder for the technical parts to be put across if it’s done with mistakes in the grammar. I know another when we were in secondary school and we wrote these papers and handed them in and our teachers gave them back with lots of red markings saying you use the passive voice here.
Bob Ducharme 00:12:42 You should have used the active voice. There are reasons for these things and like the famous Strunk and White book on Elements of Style, it makes your writing easier to read. To do things like that, it’s to imitate good writers. I mean, to vary the structure of your sentences. I mean when you’re reading someone whose reading you like, sometimes it’s nice to stop and step by and think, well, why do I like this person’s writing? Look at the structure of the sentences, into the mix up long ones and short ones and things like that. If it’s easier to read, people are going to have more motivation to read it and you want people to read it. But another point I was going to bring up, a big difference from technical writing from other typical prose writing is that people aren’t going to read what you wrote from beginning to end.
Bob Ducharme 00:13:27 You know, it’s not a novel. They picked up that documentation because they want to look something up. They want to see how to do something. And so that’s with technical writing, we typically encourage more use, making it easier to skim by doing things like bulleted lists, numbered lists, tables. If it’s just gray paragraphs on a white page, it’s a lot harder to find. I mean, you can put a lot of subheads in, I guess, and with online documentation too, it’s easier to search, which was not the case with hard copy paper. I will throw in before I forget about with lists, bulleted list versus numbered lists. I’ve seen people will often use numbered lists when they should have used a bulleted list. If I say, there are three things to remember when you’re going to do this one, boom, two, boom, three, boom.
Bob Ducharme 00:14:13 Well, are those three things, is that order really essential for that? Of course, it’s essential when you’re writing an installation guide. To do this, set these environment variables, run this script, download this, of course those steps certainly deserve to be a numbered list. But if I say, you know, there are three things to remember. I find that people often are very quick to make something, a numbered list when it doesn’t really need to be one, it should be a bulleted list. So things like that, over the lists, nested bulleted lists, listed numbered lists, these things are how we break down the information that we’re presenting so that people can skim and find the answers to the questions they have, about how to do things with your product.
Nikhil Krishna 00:14:54 That’s very interesting. And I find it interesting that you mentioned that large blobs of gray text on a page don’t kind of encourage you to read it. So, I was thinking of, what do you think about some of the newer ways I’ve seen documentation kind of get created, right? So now it’s not just text, it’s also video or images. There’s a lot of rich media that can be leveraged. So, what do you think in general of that trend? Do you think it’s something that can be considered technical writing in order of the importance of a good document? I mean, do we need to have the same kind of consideration when you’re creating your tutorial video as you do when you create an FAQ or a tutorial document?
Bob Ducharme 00:15:47 Sure. I think, when we say technical writer, I remember that there was an organization, I think I may have been a member years ago, called the Society of Technical Communicators (STC). The people who think about these other media as well. I think when you get into other media besides text, again like with software, when you’re creating something, you have to think about how maintainable is this thing I’m creating? Six months from now, if the product changes and this is obsolete, do I have to redo the whole thing? Can I go in and fix one little bit? I mean, if you wrote a series of bulleted numbered lists and you need to add one list item to one of the lists in the text, that’s easy enough. If you spent seven hours making a half hour video and, and some of the things halfway through it no longer apply, then that’s a bigger deal.
Bob Ducharme 00:16:37 I mean, even with screenshots, even with images, sometimes, I was working somewhere once where they changed the logo of the product that was in the upper left. So, everything still worked the same, but now all these screenshots, they looked outdated. And there are ways to deal with it but thinking ahead about maintainability like that, is important. And getting back to videos, imagine a 20-minute video that explains how to do 10 things. And now the fourth thing is done differently. So, you’re going to remake the whole video and that can be a real pain. So, one approach is to have a series of 2-minute videos that explain how to do a specific thing. That’s not always as easy as it sounds because some of these things might be building on each other and also managing a bunch of 2-minute videos and their relationships and making it clear to the audience, which one goes with which, there’s the maintenance is more difficult.
Bob Ducharme 00:17:31 I think videos are especially useful if it’s a graphical user interface and for demos. We click here and then here and then this pops up and look, there’s our data. And look it got processed and now we can see the results of the query or the analysis. I think that’s very useful to show how some things, although another thing about creating videos is that people can be, audio quality. Sometimes people think, well, my coworkers can hear me with his headset I’m wearing on a zoom call. So, my audio quality is fine. Whereas, I mean, you and I, we had a separate meeting before our discussion today, just to talk about mics and the rooms we’d be in and recording. So, podcasters of course care more about, think harder about, having good audio quality. Sometimes when people make videos to demo software, they’ll just use the same mic and so forth. They do it in the meeting and don’t realize that can really diminish the product.
Bob Ducharme 00:18:26 So just going out and buying a $20 Microsoft mic can help. I mean, I guess I’m kind of rambling here, but I would like to mention besides different kinds of technologies for creating documentation, along with video and images and audio, another one that’s I think being used more and more these days of especially the products that involve code, are notebooks like Jupiter notebooks, Zeppelin notebooks. Those are great because they let you format things, have your bulleted numbered lists and all that, and mix them with code that people can then see, execute themselves. Or I put in a sample, someone reading it can modify the sample and see that. So, I think that’s been a pretty exciting development in documentation of code. It doesn’t help so much with graphical user interfaces. So that was kind of rambling. I hope I addressed, if there’s anything I missed, let me know.
Nikhil Krishna 00:19:20 No, I think you did quite well. So obviously we have touched upon some of the challenges of maintaining video versus text. And that I think is also kind of brings out an underlying point, which is that software products are not a snapshots that never changed, right? Software products evolve over time. Documentation needs to be updated. And the more documentation you have of varying levels of depth, there’s always something that needs to be changed, right? So even if it is a minor version upgrade, and maybe there’s an API change that needs the reference manual could be updated, for example. So obviously this has consequences. So as people need used documents that are no longer correct, get frustrated. So from a user perspective definitely, out of date documentation is a problem. But how do you actually see, do we have a solution from a process perspective or a tooling perspective, how do you actually work with, how do you evolve the documentation along with software? Let’s say.
Bob Ducharme 00:20:29 Well, two things here. One, I guess, would be the creation, maintenance, and another would be distribution. For creation and maintenance, it’s more and more basically, you check it into the version control system. Here’s the new features for release 4.2. Here’s the write-up of release 4.2. And that way they can, they stay in sync. For distribution, what I’ve seen a lot of companies do, I mean Katana Graph does as well, is when they’re publishing the documentation, because most documentation, these days it’s going to be HTML, right? You’re going to have basically a website showing the books and the subsections and you can navigate through there. So you might have, the HTML would often include, or rather the URLs would often include the release number right in it. So, it’s like your company name.com/documentation/ 4.2 slash index HTML, and then slash 4.3 and you can leave them all up there. And then what a lot of companies will do is they’ll have your company name.com/documentation/latest, which is set to redirect to the most recent one. So that way you’re leaving all the documentation up from multiple releases at the same time as a distribution thing, but there’s still a single URL, the latest one. So that people can see what is the current state of the documentation and what is the documentation for the current state of the product.
Nikhil Krishna 00:21:51 So just to kind of also think about out loud of some of the alternatives over there. So, you mentioned versioning systems. So do you think, is that kind of like versioning systems the way we think about software versioning systems? Maybe get a sub-version, do you think that versioning that are tools like Google docs that have versions in it or even Dropbox, for example. Things like basic versioning of documents now, do you think that’s, which to you think you prefer maintaining, documentation. And also keep in mind that, okay, like we had discussed earlier. Some of that documentation might be binary, so we don’t really have a way of keeping portions of the document ID. If it’s like an image you logged and that you updated your image, you’re going to have the entire image again, try to allow a new copy of the image portion of the image. So what do you think is suitable? Is it fine to use Google docs or do you think that technical writers need to use the same during that time?
Bob Ducharme 00:23:01 They need to use the same tooling as developers. But I mean, the fact that the versioning can sync right in with the software itself, because a lot of documentation now, I mean, I could discuss this more later, but people are creating files. You’re writing files that are then going to be part of a build for documentation so that, like this HTML based distribution, I mentioned, if a designer at the company decides, oh, I don’t like this font, or we need a bigger margin here. They’re going to change some CSS and like with any website then regenerate everything. So that generation is part of it’s, it’s a built just like with software. In fact, some companies it’s part of the same built like building the software. So working with that system of the build, the use of the checking in the tools and tagging and Git, you can really take advantage of all the same things you can do with code to do that. With something like Google docs,
Bob Ducharme 00:23:55 I mean, I think it’s great for internal documentation, but I always thought the worst case with documentation. Some little companies will do is they create a Word file, right? Here’s a 5-page Word file about how to use the product. And then when a new release comes, they’ll pull up their Word file and revise, some of it. And they’ll put, I hate when they put the Word final in the file name. Maybe generate a PDF from that, or maybe even give people the Word file, which is a pretty amateurish way to do it. And Google docs is great for so many things, but the versioning of it in tying that to release versions of the software, I think you’re much better off using the tools that a software company already has in place to do that. To do Git or Bitbucket or whatever, to keep track of the pieces and the relationship of the pieces and the relationship of those pieces to the releases. So it’s sometimes for a tech writer to learn the archana of Git can be frustrating, but it’s not like you’re doing a lot of rebasing and so forth with the documentation. So you don’t have to get that far into the difficult Git weeds, in my experience so far.
Nikhil Krishna 00:25:00 Yeah. That’s a great point. And just, so you mentioned also earlier about publishing the document as a HTML website. So, one of the things I’ve noticed, especially in the open-source world is the rise of these specific things like read the tops or a specific kind of website software as a service platforms, right? Where Git books, read the docs, et cetera, where they actually handle the hosting and publication and they even have, things like searching your documentation across various versions, et cetera. So, from that perspective, do you have a process on a tool chain from building documentation from the point of, okay, I have now entered the content. So, I know this is the content that I would like to publish. And then kind of like, is that like a good tool chain that you’ve used, or maybe you can talk a little bit about your experience with older tools and stuff like that. But typically what is the tool chain that one typically uses nowadays to generate these websites and the CSS and HTML and all that?
Bob Ducharme 00:26:23 I think some of the most popular tools now are basically tools for generation of static websites that are often specialized for documentation. So, for example, where I am now, and it might in my last position that I held before we use Sphinx. With Sphinx you’re creating the actual content in restructured texts. It’s one of those markdown descendants. So Astros on either side, to bold or italics and so forth, but then you can still have your CSS and have the structure to show that these six pages here, I want to create a Table of Contents here that has those six in this order. And that all gets automated the generation of all that HTML. And when you have these files like this, the RST and the CSS and other things like that, it makes it easier to incorporate it into a version control, into Git or something like that.
Bob Ducharme 00:27:18 Then it would be if you were like revising Word files over and over. So it can be part of the software documentation tool chain. And then they’ll have a go process and some places will integrate it more deeply or not into the software build process. But as part of a release you want to make sure you’re getting the three points stuff. 3.2 stuff, 3.2 product and 3.2 code all in the same place. So it often is tightly integrated there. So I have found that very useful. And it’s also because of its relation to markdown. It’s easier for developers are used to that. So they don’t mind writing in that if I could back off and go into a little history back in the, I guess in the 1980s, there were when computerized typesetting was becoming a big thing. These companies would say, yeah, you can deliver files with codes of how you want your books laid out and where you want the fonts and all that.
Bob Ducharme 00:28:13 And in those days it could have been delivered on tape for all I know. So you put in these codes, would you want to have these codes when you want a subhead and these codes for bullets and so forth, but different competing companies doing that. They had their own sets of codes and some people, I think some at IBM in particular, I know for sure, but some other places as well, they said, wait a minute, we don’t want to tie up all of our, have all of our documentation written using your proprietary codes. We want to have more flexibility. So, they came up with a, what became an ISO standard. SGML a way to define the structure of a document and then to use that structure definition to say, you know, let’s say you’re going to have a cookbook. I want to create something it’s going to be one or more recipes.
Bob Ducharme 00:28:57 And a recipe’s title, and then it’s a list of ingredients and a list of steps. And then there’s going to be a part how many it serves. So with this SGML you could define a structure like this and then create the documents in this case, recipes, and then automate the checking of those that structure confined to, does it follow the structure that I defined? And if you, if you note it follows a structure, you could automate a lot more. You can then turn, and this is in the early days of multimedia getting beyond paper. I’m going to turn it into online, help. I’m going to turn into CD ROMs. I’m going to turn into HTML. And so I got involved in HTML and I would go to the conferences and I got to know some of the people who did it.
Bob Ducharme 00:29:35 And some of them realized SGML and some of the software was very expensive doing this. Some of the SGML was very complicated. So, some of these people got together and thought we need to create a simpler, easier version of SGML. Something that wouldn’t take so much computing power, something that could be parsed with a program that’s you can just download over the internet with this new language, Sun Microsystems has called Java. So that was 90’s, I guess? So, they were working on the simplified version of SGML. They first, the first original working title for it was Web SGML, not as catchy. And then someone thought of a catchier name, XML. And that’s where XML comes from. It was a simplified version of SGML. So, a lot of the tool chains SGML when it was invented for this, that’s what places like Boeing and large defense contractors to document the engine parts they were thinking back then, that documentation, we should treat it like software in terms of breaking it down into components.
Bob Ducharme 00:30:36 If this subsystem of this engine is also used on other engines as well, we should be able to write up how to clean, how to repair this sub system and then take that write up and add it to the documentation for the other engines as well. So those were some of the early moves toward making documentation componentize, just like software so that it could be mixed and matched and used for different products. And there would be the tool chains for SGML and later XML to do what I was saying about syncs now that you would have your CSS here you’d have tools for generating the HTML from there, or the online help or the CD rom. Developers didn’t like dealing directly with the XML as much, markdowns are a little simpler. And there were tools to be a little more gooey-ish, a little look, a little more like WORD that would still output the appropriate XML, but sometimes those could be expensive.
Bob Ducharme 00:31:30 So that’s another sort of lineage of the tool chain for creating software documentation, hardware, documentation is XML and related tools. People don’t realize that that’s what XML was for because when it was XML was first invented, it was around the time of the.com boom. And with the.com boom, early 2000’s. There were people, you know, we’re going to have seamless e-commerce and have this computer communicate with that other one across the web to send the orders and respond to the orders, but sending and responding to these orders, they had to send these batches of data that didn’t necessarily fit into CSV. They would have more complicated structures than that. So they saw this XML thing from the W3C. We can define our own structures. You know, here’s the beginning of a order, here’s the end, here’s the address, here’s the list of items being ordered and so forth. So they started using XML for that, to do this E-commerce. Basically the kind of things people are using Jason for now. They started using it and thought, this is perfect. And then they decided, no, this isn’t perfect at all. That the data typing system is weird and whoever designed it did a terrible job. Well, they didn’t realize that whoever designed XML was not designing it for the uses they were putting it for. For handling arbitrary handfuls of data about transactions back and forth.
Nikhil Krishna 00:33:28 Just to quickly just jump in on over there. So, I remember that we went down this whole path with XML about the web status, the Ws star, and the whole set of VEP service X amount of standards. I think one of the, maybe the things that kind of led to the adoption of Json and the standards like that was the fact that you have all of the sediment here how, what the document should be like. But I also remember at that time, there was this competing, speaking for documentation, there was this other thing called RDF, right? And I was just wondering, was that actually something that could have, if appropriately championed being something that kind of to go over the documentation side of things that XML kind of was meant to have, or meant to be for?
Bob Ducharme 00:34:25 No RDF is great at metadata documents, but to have a series of paragraphs with sentences where there’s inline thing in the middle of a sentence, I have a link, I have a bolded term, RDF is not good for that. Our RDF is about reducing data down to these three parts statements called triples. So I can say employee 38 has a hire date of January 1st, employee 38 has the last name of Smith. And then the flexibility that RDF gives you over something like a relational database enables a lots of new things, including the ability to aggregate data from different sources and things like that. And I mean, I could go on and on about RDF, but for linear
Nikhil Krishna 00:35:07 So it does more of that something that XML was trying to aim to be that what the website was perhaps a better way of doing it.
Bob Ducharme 00:35:21 You know for something like Json, you’re better off, I think. With RDF, the metadata, when you have especially a lot of, in the field of digital humanities and a lot of publishers, they have content from lots of different places and they want to keep track of the content and that content, in those different things will have different bits of metadata, but sometimes they’re related, even though they’re different because from this standards, body or that one, and so mapping between the standards of the dig and then query across all their metadata for a range of thess, RDS really good for that. But not for the content itself, the sort of narrative content of paragraphs and bulleted and numbered lists. We could do whole cast on RDF.
Nikhil Krishna 00:36:00 Yeah. So to come back a little bit on back to our technical documentation topic, one of the things that I’ve seen, you mentioned using swings and the tool chains like that. And we also discussed some of the older tools like SGML and XML, but it seemed to be sometimes that depending on the type of documentation, some of those is more automatable and others are less, right? So, for example, we talked about earlier in what kind of technical documentation should be generated. We talked about FAQ’s tutorials, high-level technical documents, which explain things to non-technical people. But at the same time, if you have something like a Jess on API or HPP API, we also have tools that like Swagger, which you can just find that the, the specifications or the API itself, in some cases kind of generates the documentation out of it, right?
Nikhil Krishna 00:37:10 It’s almost like you can look at the types of the various response requests and that kind of create a document that allows you to, in some cases, even create sample example requests and responses that you can use for testing. But I sometimes get the feeling that, okay, that is again, too low level. Where do you see the balance between the two should be? And how much of the documentation that is generated for a software project can be generated like that? And how much of it is still something that you want to make sure that you write in the proper manner?
Bob Ducharme 00:37:52 That’s a good question. I think, like I mentioned something like a tutorial, you really want to think carefully about the order you’re going to explain things in what you have the person do of the three buckets. I mentioned of tutorials, reference guides and user guides. With reference guides, it can be a little more automated like with Swagger, I’ve used it but I can’t remember the name. Is that, was that the tool you mentioned that can pull things out of APIs and generator?
Nikhil Krishna 00:38:20 Yeah. So spider is basically part of the open MPI. I think it’s called the Json API documentation tooling and what it does is it looks at Json’s documents and kind of generates the request agenda web-based documentation, which has which details on all the lists of all the attributes properties and then the types of it. Which isÖ
Bob Ducharme 00:38:47 And I believe it will pull out
Nikhil Krishna 00:38:50 Yeah, it pulls out some of the comments as well from the front, from the function. So you can get a high level, two line description of what the API does, but then that depends on how well, if
Bob Ducharme 00:39:02 Exactly, and, and that’s garbage in garbage out. I mean, that’s a tool that can go through and pull out and see, oh, this function takes three parameters and the parameters are supposed to be of these types. And it returns something of this type. That’s nice to automate the pulling of all that and the enumeration of it, but this, the doc strings, how often have we seen doc strings? So just explain what we wanted to explain. So, and that can be a tech writer function to, to review that documentation and then maybe create some tickets and say, hey, you go back and revise that doc string to explain that better. One of my pet peeves is whether it’s explaining the fields on a dialog box or parameter being passed to a function. If we say here’s a parameter called Fu and the documentation says, enter the Fu value there. And I’m thinking, okay, but what is Fu? What role does Fu play in this application? And what kind of things might I put there? So the explanation that goes in there, tools like that, they’re like naked tools. It’s great how they can pull everything together and then create the thing you’re looking for. But the things they’re pulling together have to have some quality in them and sometimes they can help point to which parts need to be updated, but still it’s garbage in garbage out.
Nikhil Krishna 00:40:22 Right. So now that you mentioned that he had talked about keeping and using the same Git tooling and the motion tooling and trying to keep the documentation versions the same as the software. So as every portion of software, you also bought the version of documentation that kind of maintain that. So basically we may, if we kind of, from a process perspective, say being self-aware as a software engineer, we basically approached doc strings or comments. And we kind of write a proper explanation for every function. And basically try to use that as documentation. Do you think that theoretically, it is possible to kind of mix that in. Do you still feel that there is a separate place, require a separate folder or maybe a separate project within your Git repository that you should keep a separate viewpoint, separate perspective, or a separate type of documentation?
Bob Ducharme 00:41:29 This really gets back, I think, to the distinction between reference guides and user guides. Reference guides that is all reference guide stuff. You know, you want to list everything. I mean, I think when someone looks at a product and they see some strange icon or menu choice and think, well, what’s that for? The reference guide is where they would look it up to find it out. In fact, with a graphical user interface, and this can be difficult, but I think it’s important. Every tool tip should be, if there’s some strange icon, you don’t know what it means, but you mouse over it and you see some tool tip. That tool tip should be something that the user can search on in the reference guide. And, I’ve worked places where I had to tell the customer developers before each new release, which tool tips got changed?
Bob Ducharme 00:42:11 I want to be able to name all the tool tips in the documentation, because that’s the hook for people to find out what the icon is for. So a lot of the reference guides for not only for technical things like APIs, but even for the gooey, because for the graphical user interface to explain everything they see, they should be able to look up what that is. On the other hand, a point I wanted to bring up about user guides is that well, I mentioned how, when I wrote up Table of Contents for an XSLT book, I didn’t use any XSLT terms. I talked about the tasks to do. If let’s say, for example, your product has a component to develop a schema and it’s called Schema Wiz, okay? And you’re going to document that, to me if the user guide has a header called Getting Started with Schema Wiz, that’s not a very good title.
Bob Ducharme 00:43:00 I mean, I want to see titles like Creating a New Schema, Revising an Old Schema, Deleting Schemas. Naming the tasks that need to be done as opposed to using the terms you made up for your product as part of the driver of the user guide. So I guess to get back to your question about a place for something separate from the, the list of things, that’s where the user guides go. To something organized by the tasks they want to do, as opposed to something that is organized by the product itself, being organized by the product itself is still important because that’s where they see something on the product that, that’s where they go the reference guide to see what is this thing for? What good will this do for me? So, I guess to simplify, to getting back to your original question, that is the distinction to me between reference guides and user guides.
Nikhil Krishna 00:43:48 Right. So again, nowadays basically there is this idea of an X Esco philosophy, right? So, you have dev sec ops documented. So, we have security as code configuration, Esco X, something else. This is philosophy that everything kind of starts becoming encode. We kind of been discussing how close documentation is and our how they are with code, so should we be treating, approaching our documentation as code and kind of completely have, not just the portion control, have software processes for it. So, we can have like who to request for documentation, the ICD for other documentation. We have like a review process. We have like, we have documentation reviews. What do you think about this particular? What is your opinion on this?
Bob Ducharme 00:44:51 I mean, I agree with it. I think that treating it as code, lets you take advantage of all these tools that you have that you already have to work with your code. So, for example with reviews, review of documentation, like code reviews, a lot of companies, I write something I need it reviewed. I created a journal ticket, to assign someone to review it. And then we say this, this feature is held up until someone does the review, just like when someone’s reviewing some C code that was written. So, I think that treating it as code has the advantage of letting you take advantage of all these tools. We just, why the old-fashioned way of creating a WORD file to have the documentation there. It doesn’t let you take advantage of these tools and things. So, using the tool set is the advantage you get from treating it as code. So, I think that’s been encouraged in a lot of places right down to the use of JIRA tickets to assign documentation tasks.
Nikhil Krishna 00:45:46 Okay. So then if given that right, that in smaller companies, it is also often the role of whoever’s doing the software documentation to also develop things for marketing, right? And for Sales. So, then you have like in startup, you might have the same technical writer or even software developer, for example, being approached by the marketing department and saying, Hey, okay, we would like you to write-up something about this particular feature that we can post or share with the email newsletter, for example. Do you think the skills required for this kind of writing, writing marketing content and writing sales content, how similar is that? Or how different is it from writing technical documentation?
Bob Ducharme 00:46:42 I think it’s very similar because, especially when you’re writing technical documentation, things like tutorials, as I mentioned, and even release notes, I considered to essentially be marketing documents because with both the tutorial and release notes, what you’re seeing is look at this cool stuff. Isn’t this great? Here’s this thing for you to use. So I think of them as, as marketing documentation. Marketing communications is a way to sell things. To say, what are the great things about the product and why people should be interested in using it. Within an organization you’re sometimes working with the marketing people. You become the tech editor, they might start throwing the things that make your product cool, maybe associated with buzzwords that they like to throw around, but don’t understand, that’s pretty common. So making that technical documentation more, making the marketing communications more technically accurate, I think is a big part of that. And they’re usually happy to have you right? Or a couple of places I’ve worked where they’ll have a software developer write a blog entry. And then you, as the tech writer, rearrange it a bit to make it more, user-friendly not only to customers, but to potential customers. I mean, people who just came across your blog and are even more on technical, but they can get maybe buying the product so that the technical writer is sort of coordinating between developers and marketing people to help create new blog entries.
Nikhil Krishna 00:48:09 So we should also include this category into our idea of documentation as code and kind of subjected to the same kind of processes. Do you think that that’s to work? So, is that something that is difficult to do when you start involving third parties like sales and marketing and all of those people who may not be familiar with it?
Bob Ducharme 00:48:36 Yeah, probably not the same processes because, you know, sales and marketing people it’s, you know, assigning them tickets and having them check things into Git, it might be a bit too much to ask for. But I think helping them to coordinate the content itself to make sure that it is technically accurate, but well-written, that all is, I think very useful and they’re probably going to have their own tools. You know, they might be creating PowerPoint presentations and they want your help with that or Word files that they are going to turn into PDF. So, they’re going to have their own processes and the developer processes of using Git and so forth is probably going to be over their heads. But, you know, you’re the liaison between them, between the marketing people and the developers. It’s your job as a tech writer to translate the technical stuff to the non-technical people. So that is an interesting place to help apply that. To helping with the marketing.
Nikhil Krishna 00:49:27 Awesome. So, Bob I think we’ve kind of reached the end of what I had in mind. In our conversation so far, we’ve talked about software documentation from the perspective of a reference manuals and user manuals and guides and things like that. There’s also, especially if you’re writing, if you’re part of a software project, that’s a pretty substantial surprise software product you might be asked, well, can we create a book grant? Can we create some kind of substantial artifact out of it? Right? So maybe we publish a book about the project. Is that the same as, or similar to, in terms of process, to creating technical documentation? Do you think a book is a good way of writing about a software product that keeps changing and keeps evolving, just a couple of questions?
Bob Ducharme 00:50:27 Well, you could, I mean the user guide material you have, that that could be an output format. There are ways to just turn that into a hard copy book, but I think a related issue about a book is that some people will we’ll see, okay, O’Reilly has a bunch of books about Oracle products. You know, that would be cool if there was an O’Reilly book about our product or Manning or one of the big computer publishers, some workplaces where people thought, oh, wouldn’t that be cool? And writing a separate book to go with a publisher. I mean, some publishers will work with you to do a short book that you can then give away, but you know, that’s going to cost you money, but to write a complete book about something that is a sort of separate entity from a separate publisher, it’s fun when it’s done, but it’s a lot more work than people realize.
Bob Ducharme 00:51:13 And you know, we were talking earlier about one of the issues of making videos is you put a huge amount of work in something that could be obsolete six months later. If you’re going to put five or 600 hours into writing a book that is going to be, that could potentially be obsolete a year later, a year and a half later. And that’s an important thing to think about the resources that go into the creation of the book. And when I’ve written books, they’ve usually been about standards because standards move more slowly in their upgrades than products from companies. So, if you’re writing about release 3.2, when 3.5 is out, people aren’t going to look too hard at your book and it can be a lot more, some people will they’ll think like, well it takes me half an hour to write a page.
Bob Ducharme 00:51:59 So a 300-page book that would take me 150 hours and that’s not how it works. You know, one of the reasons you could write that page in half an hour is because you already had that page’s worth of content in your head, all organized. There’s a lot more work to do to organize the content for 300 pages. Secondly, even if you could write 300 pages in 150 hours, that’s just your first draft. It’s got to go through additional drafts just to improve the writing to make sure it’s technically correct. Plus, you’re going to have a lot of research to do. Some people think, oh, well, we could do it in half the time if two people wrote it together, but it’s going to be more like 70% of the time because you have to coordinate what you’re doing. And then once the thing gets upgraded your book is going to look out of date. So there are some highlights to writing a book about your software to be published by a publisher that — I was going to say puts things in bookstores. We don’t see that so much, but — puts things on Amazon where people can buy the book, but it can be a lot more work and you have to consider how quickly it will become obsolete. Once you have an upgrade or two, it’s all this work you did as already history. Does that address what you were asking? I was kind of rambling there.
Nikhil Krishna 00:53:07 I think that’s a great overview of some of the challenges of book writing, and I’m sure not the least of it is also the different process that the book publishers might have. Right? It might not be the same thing that you’re used to following with your technical articles where you probably editorial oversight as well. But yeah, I think that’s, that’s a great point to kind of end this podcast. I just wanted to ask if listeners would learn to follow or contact you, if there are, maybe you’d like to talk about some of the things that you’re working on right now, this is your chance.
Bob Ducharme 00:53:50 If people want to contact me on Twitter, I’m @Bob DC, B O B D C. And also I did manage to get many years ago, the domain name, BobDC.com. So, you can find out more about the books I’ve written and that’s also where I have my blog. So there are several, I can send you a link to put in the show notes of a series of blog posts. I did several years ago, really about writing documentation, about some of these issues we’ve covered and some other things to keep in mind.
Nikhil Krishna 00:54:15 Awesome. We will definitely add that to the show notes, and I guess all that means is thanks. Thank you, Bob. This has been a pretty engaging conversation. I think this it’ll be very valuable to our listeners. Thank you for spending the time with us.
Bob Ducharme 00:54:33 Well thank you for having me. It’s going to be fun driving around in my car, listening to a podcast where I’m the one talking. I’m sure you’re used to that by now, but it’s been a lot of fun. And I love talking about this stuff.
Nikhil Krishna 00:54:43 Thank you Bob. [End of Audio]
SE Radio theme: “Broken Reality” by Kevin MacLeod (incompetech.com — Licensed under Creative Commons: By Attribution 3.0)
Great discussion. You hit on all the topics and paths that I talk about seemingly every week. Thanks!