Episode 501: Bob Ducharme on Creating Technical Documentation for Software program Initiatives : Software program Engineering Radio


Bob DuCharme, an skilled technical author and creator talks about writing documentation for software program merchandise. On this episode we focus on the assorted sorts of documentation that one creates for software program merchandise. Host Nikhil Krishna spoke with Bob in depth in regards to the distinction between these kinds of documentation and the audiences they aim; significance of utilizing correct grammar and readability in writing good documentation that folks need to learn; different types of documentation (photographs, video and audio); challenges of sustaining and updating documentation; maintaining documentation in sync with merchandise; toolchains for constructing documentation; historical past of software program documentation tooling and requirements.
This episode sponsored by OpenZiti.

Transcript delivered to you by IEEE Software program journal.
This transcript was routinely generated. To counsel enhancements within the textual content, please contact content material@laptop.org and embrace the episode quantity and URL.

Nikhil Krishna 00:01:05 Hi there and welcome to Software program Engineering Radio. I’m Nikhil and I’m a brand new host on Software program Engineering Radio, and I’ve the pleasure to introduce Bob DuCharme. Bob is an achieved author, software program engineer, and an information architect who has been concerned with the semantic net since 2002. Bob is an creator who has written books for O’Reilly, Manning, and Prentice-Corridor — particularly, Studying SPARQL, XSLT Shortly, and The Annotated Specification and SGML CD for Prentice-Corridor. He’s additionally written in magazines, so he has written for the Modalities journal, O’Reilly Networks, XML.com, Dr. Dobbs channel, and even IBM technical books. He’s presently a technical author at Katana Graph, makers of a high-performance distributed graph database, and is predicated in Charlottesville, Virginia, and has 5 books and practically 100 on-line and print articles about IT. Bob is proud to have by no means used the phrase “performance” in any of them. Bob, is there something in your bio that I would’ve missed or that you just want to add?

Bob Ducharme 00:02:16 I feel you’ve obtained the important thing issues. I imply, I’ve form of gone forwards and backwards between software program growth — answer architect is all the time such a obscure time period, however you already know, serving to clients determine what they’re going to do — and writing it up. So typically extra coding, however proper now I’m comfortable to be ready the place I’m just about a full-time author.

Nikhil Krishna 00:02:35 Superior. To present listeners just a little little bit of an outline on what they’re going to do on this specific episode, we’re speaking about creating technical documentation. So, clearly there are numerous sorts of documentation and you’ve got a job as a technical author proper now in Katana Graph. So maybe we must always begin with just a little bit in regards to the technical author function itself. So, the primary query could be, why do we want this function? Why is the technical author vital for a software program group?

Bob Ducharme 00:03:06 Sometimes, when individuals get a product, they need to know how one can use it. And there are good programmers on the market who know their favourite languages inside out and all of the cool issues you are able to do and how one can do them effectively. However these builders may not know how one can clarify the tip person utilization of these merchandise to people who find themselves new to it. So, explaining to individuals, determining what they’re going to need to lookup and how one can do this stuff, that’s actually the tech author’s job: you already know, to put in writing the person handbook, mainly, the person handbook or/and reference information and different issues like that, which we are able to discuss have overlapping duties. However individuals will get a software program product, they need to know how one can use it, so the tech author is the one that explains how one can use it.

Nikhil Krishna 00:03:50 Cool. So simply to dig in just a little bit, what are the specialised expertise? So, what does the technical author deliver to the job that perhaps a software program engineer with an English talking background can’t do?

Bob Ducharme 00:04:03 Nicely, sometimes to get pleasure from writing. I imply, lots of people simply don’t prefer it; they view it as an terrible chore. Perhaps any individual writes on the aspect or has a weblog or one thing like that, however you want to have the ability to discuss and talk with on one hand the tip customers and however with software program builders to know the technical components. If a developer has a brand new function and says, right here’s what it does, and that’s not clear, the technical author has to have the ability to ask the fitting inquiries to say, ‘I get this half and this half, however this half right here, how does that work?’ They should form of interview them to seek out out the data vital, to then clarify it to people who find themselves new to the product who don’t have that technical background. So, the communication talent goes in two instructions. One, to the end-user and two to the extra technical individuals, the builders.

Nikhil Krishna 00:04:50 So, does that imply that the technical author must have a software program engineering background as a result of if he’s speaking to software program builders about technical matters, does that imply that that you must have that very same language of similar vocabulary to have the ability to perceive?

Bob Ducharme 00:05:08 It helps. I do have, since I first grew to become a technical author, I alongside the best way did get a grasp’s in laptop science. And that has helped me loads to know the technical discuss and likewise to assist kind out precise technical phrases from buzzwords, which is one other factor, as a result of, you already know, you hear these phrases getting thrown spherical. A few of them have particular meanings, a few of them get misused. So, I’ve typically joked in some locations that I’ve labored at having a grasp’s in laptop science helps me to speak to the PhDs. After which translate what they’re saying to common individuals. So it helps, nevertheless it’s not essentially, particularly if the product is — some merchandise may have finish customers who’re non-technical. If it’s a telephone app to assist monitor one thing, however some merchandise may have technical finish customers, particularly for those who’re going to be writing about, an API or one thing like that. The flexibility to speak with the builders turns into an increasing number of essential then the extra technical viewers is.

Nikhil Krishna 00:06:05 Superior. So once more, simply to sort of elaborate just a little bit on that. So what sort of documentation, technical author sometimes give attention to? Do they really create design or structure paperwork? Or is it extra like user-facing documentation, like manuals and installations? Is that, I suppose a operate of what sort of software program undertaking you might be writing documentation for? Or is that this one thing that as a regular is all the time going to be written by a technical author?

Bob Ducharme 00:06:38 I might say that you just’re, if somebody has a technical author function there, their major job is to put in writing user-facing documentation. These form of structure diagrams and stuff, it’s attention-grabbing to see these, and people are good background after they’re creating. But when an organization goes to price range to have a tech author that’s to have somebody who creates that a part of the product. The a part of the product that helps finish customers rise up and operating. And there’s three primary sorts of person documentation. And once I first began this, it was again within the day when there have been printed documentation. We’d make three separate volumes for this on the locations the place I labored. The primary could be a reference information. A reference information ought to clarify mainly every little thing any individual sees within the product, each icon, each menu selection. In the event that they take a look at one thing and assume, what good is that?

Bob Ducharme 00:07:20 What’s that for? They need to have the ability to shortly discover it and look it up and see what it does. After which aside from the reference information, the opposite large one could be the person information. A person information is organized extra by way of the duties that the tip person needs to do. The person information is de facto geared toward somebody who doesn’t know the product. So, for instance, if it’s a database program, it might say how one can create a brand new database, how one can put information in there, how one can edit it. You’d talked about, I wrote a ebook referred to as “XSLT Shortly” for Manning, which was in regards to the XSLT language for manipulating XML. And I had come from a background with SGML earlier than that; XML is mainly a less complicated model of SGML. And my work with SGML enabled me to, once I wrote the define for the XSLT ebook, earlier than I even knew how one can write any XSLT, I used to be nonetheless in a position to write a person information define as a result of I knew what the duties individuals needed to do have been: Create new components, rename components, convert components to attributes and forwards and backwards, delete, rename.

Bob Ducharme 00:08:17 I knew what the fundamental duties have been, in order that I may create an overview that stated issues like, Easy methods to Create Parts, Easy methods to Delete Parts, Easy methods to Rename Attributes, and so forth. So, when somebody’s taking a look at a person information, they need to see the names of the duties. The person information shouldn’t be speaking within the technical language, or at the least the Desk of Contents shouldn’t be speaking within the technical language of the product. It must be speaking by way of the duties that customers need to get completed. And that’s not all the time simple as a result of it’s important to, perhaps work with advertising and marketing and work with a few of the UI builders to seek out out, to know the customers, what are they making an attempt to do with this product? What are the assorted issues? How do these issues match collectively? You actually must get contained in the person’s head, so you may then clarify right here’s how to do that. Right here’s how to do that. And that brings me to the third class of documentation together with reference information and person guides could be, I would name it a fast begin or getting began, however a tutorial. Generally I’ve seen getting began to cowl set up as effectively, however a tutorial for somebody who’s by no means used the product, which I contemplate nearly like a demo, like giving a demo to your self, you already know: the 1st step, click on right here, step two, click on right here on this comes up. That’s for this nice motive, as a result of to form of exhibit the cool components of the product, perhaps even it’s in a means, just like what somebody giving a demo in entrance of a convention may do. To undergo 10 or 15 steps to indicate the cool components of the product. The tutorial, I feel, is one thing the place a script somebody can provide that demo to themselves and see how cool the product is and how one can do the fundamental issues. So these, I suppose, could be the three classes, reference information, person information, and a fast begin tutorial.

Nikhil Krishna 00:09:50 In order a software program developer, if I’m on this area, what are the talents I have to domesticate? Perhaps are there some easy pointers that as builders, we are able to comply with to enhance our documentation for perhaps our aspect undertaking? Or perhaps even when it’s not our undertaking and we’ve been requested to do some documentation, what are some easy pointers or issues that we are able to do to ensure that we’re writing good technical documentation?

Bob Ducharme 00:10:23 And right here’s one thing I’m in all probability going to say loads: there are lots of analogies to writing the software program itself. So, for instance, with documentation, if the software program was developed from a well-organized set of necessities, these necessities are going to be very helpful to you. You realize, there’s this listing saying clients ought to have the ability to do that, clients ought to have the ability to do that, buyer ought to have the ability to do that. So, in case you have some well-written necessities, that’s a terrific place to start out. Right here’s how to do that, right here’s how to do that. Different issues embrace, I all the time like to consider two lessons of reviewers. Whenever you write, explaining one thing, you need to present it to, in fact, a developer or somebody to just remember to defined it appropriately, that you just didn’t get something unsuitable. However you additionally need to, what I name a target market reviewer — somebody who doesn’t know the product however has some curiosity in studying the product; have them learn what you wrote and see, may they comply with alongside? Did your clarification work for them? And if not, the place? So these two sorts of reviewers I feel, are essential to remember once you’re creating one thing.

Nikhil Krishna 00:11:26 Okay. So, are there any easy issues that we are able to do by way of the language itself? So perhaps, it is a great way of placing, so is grammatical accuracy completely write to? Or is it okay to say, okay so long as I’m technically correct some grammatical situation are effective, it’s not that robust. What do you assume?

Bob Ducharme 00:11:57 Nicely, I imply grammar it’s not like, once you’re writing code and for those who forgot a semi-colon the entire thing’s not going to compile, proper? It’ll nonetheless be there. But when the grammar is dangerous, it’s in all probability going to be tougher to know. You realize, in case you have a plural topic with a singular verb, individuals studying it, aren’t going to cease and return and it’s going to be tougher to comply with. So, I feel grammatical accuracy, easy issues like that and punctuation, this stuff I feel are essential. It’s going to be tougher for the technical components to be put throughout if it’s completed with errors within the grammar. I do know one other after we have been in secondary college and we wrote these papers and handed them in and our academics gave them again with a number of pink markings saying you utilize the passive voice right here.

Bob Ducharme 00:12:42 You must have used the lively voice. There are causes for this stuff and just like the well-known Strunk and White ebook on Parts of Type, it makes your writing simpler to learn. To do issues like that, it’s to mimic good writers. I imply, to differ the construction of your sentences. I imply once you’re studying somebody whose studying you want, typically it’s good to cease and step by and assume, effectively, why do I like this individual’s writing? Have a look at the construction of the sentences, into the combo up lengthy ones and quick ones and issues like that. If it’s simpler to learn, persons are going to have extra motivation to learn it and also you need individuals to learn it. However one other level I used to be going to deliver up, a giant distinction from technical writing from different typical prose writing is that folks aren’t going to learn what you wrote from starting to finish.

Bob Ducharme 00:13:27 You realize, it’s not a novel. They picked up that documentation as a result of they need to look one thing up. They need to see how one can do one thing. And in order that’s with technical writing, we sometimes encourage extra use, making it simpler to skim by doing issues like bulleted lists, numbered lists, tables. If it’s simply grey paragraphs on a white web page, it’s loads tougher to seek out. I imply, you may put lots of subheads in, I suppose, and with on-line documentation too, it’s simpler to look, which was not the case with exhausting copy paper. I’ll throw in earlier than I neglect about with lists, bulleted listing versus numbered lists. I’ve seen individuals will typically use numbered lists when they need to have used a bulleted listing. If I say, there are three issues to recollect once you’re going to do that one, increase, two, increase, three, increase.

Bob Ducharme 00:14:13 Nicely, are these three issues, is that order actually important for that? After all, it’s important once you’re writing an set up information. To do that, set these atmosphere variables, run this script, obtain this, in fact these steps definitely should be a numbered listing. But when I say, you already know, there are three issues to recollect. I discover that folks typically are very fast to make one thing, a numbered listing when it doesn’t actually have to be one, it must be a bulleted listing. So issues like that, over the lists, nested bulleted lists, listed numbered lists, this stuff are how we break down the data that we’re presenting so that folks can skim and discover the solutions to the questions they’ve, about how one can do issues along with your product.

Nikhil Krishna 00:14:54 That’s very attention-grabbing. And I discover it attention-grabbing that you just talked about that enormous blobs of grey textual content on a web page don’t sort of encourage you to learn it. So, I used to be pondering of, what do you consider a few of the newer methods I’ve seen documentation sort of get created, proper? So now it’s not simply textual content, it’s additionally video or photographs. There’s lots of wealthy media that may be leveraged. So, what do you assume typically of that pattern? Do you assume it’s one thing that may be thought-about technical writing so as of the significance of an excellent doc? I imply, do we have to have the identical sort of consideration once you’re creating your tutorial video as you do once you create an FAQ or a tutorial doc?

Bob Ducharme 00:15:47 Certain. I feel, after we say technical author, I keep in mind that there was a corporation, I feel I’ll have been a member years in the past, referred to as the Society of Technical Communicators (STC). The individuals who take into consideration these different media as effectively. I feel once you get into different media apart from textual content, once more like with software program, once you’re creating one thing, it’s important to take into consideration how maintainable is that this factor I’m creating? Six months from now, if the product modifications and that is out of date, do I’ve to redo the entire thing? Can I am going in and repair one little bit? I imply, for those who wrote a collection of bulleted numbered lists and that you must add one listing merchandise to one of many lists within the textual content, that’s simple sufficient. For those who spent seven hours making a half hour video and, and a few of the issues midway by means of it now not apply, then that’s a much bigger deal.

Bob Ducharme 00:16:37 I imply, even with screenshots, even with photographs, typically, I used to be working someplace as soon as the place they modified the emblem of the product that was within the higher left. So, every little thing nonetheless labored the identical, however now all these screenshots, they seemed outdated. And there are methods to cope with it however pondering forward about maintainability like that, is essential. And getting again to movies, think about a 20-minute video that explains how one can do 10 issues. And now the fourth factor is completed in another way. So, you’re going to remake the entire video and that may be an actual ache. So, one strategy is to have a collection of 2-minute movies that specify how one can do a particular factor. That’s not all the time as simple because it sounds as a result of a few of these issues is likely to be constructing on one another and likewise managing a bunch of 2-minute movies and their relationships and making it clear to the viewers, which one goes with which, there’s the upkeep is tougher.

Bob Ducharme 00:17:31 I feel movies are particularly helpful if it’s a graphical person interface and for demos. We click on right here after which right here after which this pops up and look, there’s our information. And look it obtained processed and now we are able to see the outcomes of the question or the evaluation. I feel that’s very helpful to indicate how some issues, though one other factor about creating movies is that folks might be, audio high quality. Generally individuals assume, effectively, my coworkers can hear me along with his headset I’m carrying on a zoom name. So, my audio high quality is ok. Whereas, I imply, you and I, we had a separate assembly earlier than our dialogue at present, simply to speak about mics and the rooms we’d be in and recording. So, podcasters in fact care extra about, assume tougher about, having good audio high quality. Generally when individuals make movies to demo software program, they’ll simply use the identical mic and so forth. They do it within the assembly and don’t understand that may actually diminish the product.

Bob Ducharme 00:18:26 So simply going out and shopping for a $20 Microsoft mic will help. I imply, I suppose I’m sort of rambling right here, however I want to point out apart from completely different sorts of applied sciences for creating documentation, together with video and pictures and audio, one other one which’s I feel getting used an increasing number of nowadays of particularly the merchandise that contain code, are notebooks like Jupiter notebooks, Zeppelin notebooks. These are nice as a result of they allow you to format issues, have your bulleted numbered lists and all that, and blend them with code that folks can then see, execute themselves. Or I put in a pattern, somebody studying it might modify the pattern and see that. So, I feel that’s been a reasonably thrilling growth in documentation of code. It doesn’t assist a lot with graphical person interfaces. In order that was sort of rambling. I hope I addressed, if there’s something I missed, let me know.

Nikhil Krishna 00:19:20 No, I feel you probably did fairly effectively. So clearly we now have touched upon a few of the challenges of sustaining video versus textual content. And that I feel can also be sort of brings out an underlying level, which is that software program merchandise will not be a snapshots that by no means modified, proper? Software program merchandise evolve over time. Documentation must be up to date. And the extra documentation you’ve got of various ranges of depth, there’s all the time one thing that must be modified, proper? So even when it’s a minor model improve, and perhaps there’s an API change that wants the reference handbook might be up to date, for instance. So clearly this has penalties. In order individuals want used paperwork which are now not appropriate, get annoyed. So from a person perspective undoubtedly, old-fashioned documentation is an issue. However how do you truly see, do we now have an answer from a course of perspective or a tooling perspective, how do you truly work with, how do you evolve the documentation together with software program? Let’s say.

Bob Ducharme 00:20:29 Nicely, two issues right here. One, I suppose, could be the creation, upkeep, and one other could be distribution. For creation and upkeep, it’s an increasing number of mainly, you verify it into the model management system. Right here’s the brand new options for launch 4.2. Right here’s the write-up of launch 4.2. And that means they will, they keep in sync. For distribution, what I’ve seen lots of corporations do, I imply Katana Graph does as effectively, is after they’re publishing the documentation, as a result of most documentation, nowadays it’s going to be HTML, proper? You’re going to have mainly a web site displaying the books and the subsections and you’ll navigate by means of there. So that you may need, the HTML would typically embrace, or somewhat the URLs would typically embrace the discharge quantity proper in it. So, it’s like your organization identify.com/documentation/ 4.2 slash index HTML, after which slash 4.3 and you’ll depart all of them up there. After which what lots of corporations will do is that they’ll have your organization identify.com/documentation/newest, which is about to redirect to the latest one. In order that means you’re leaving all of the documentation up from a number of releases similtaneously a distribution factor, however there’s nonetheless a single URL, the most recent one. So that folks can see what’s the present state of the documentation and what’s the documentation for the present state of the product.

Nikhil Krishna 00:21:51 So simply to sort of additionally take into consideration out loud of a few of the alternate options over there. So, you talked about versioning programs. So do you assume, is that sort of like versioning programs the best way we take into consideration software program versioning programs? Perhaps get a sub-version, do you assume that versioning which are instruments like Google docs which have variations in it and even Dropbox, for instance. Issues like primary versioning of paperwork now, do you assume that’s, which to you assume you favor sustaining, documentation. And likewise remember that, okay, like we had mentioned earlier. A few of that documentation is likely to be binary, so we don’t actually have a means of maintaining parts of the doc ID. If it’s like a picture you logged and that you just up to date your picture, you’re going to have the complete picture once more, attempt to enable a brand new copy of the picture portion of the picture. So what do you assume is appropriate? Is it effective to make use of Google docs or do you assume that technical writers want to make use of the identical throughout that point?

Bob Ducharme 00:23:01 They should use the identical tooling as builders. However I imply, the truth that the versioning can sync proper in with the software program itself, as a result of lots of documentation now, I imply, I may focus on this extra later, however persons are creating recordsdata. You’re writing recordsdata which are then going to be a part of a construct for documentation in order that, like this HTML based mostly distribution, I discussed, if a designer on the firm decides, oh, I don’t like this font, or we want a much bigger margin right here. They’re going to alter some CSS and like with any web site then regenerate every little thing. In order that technology is a part of it’s, it’s a constructed similar to with software program. In truth, some corporations it’s a part of the identical constructed like constructing the software program. So working with that system of the construct, the usage of the checking within the instruments and tagging and Git, you may actually benefit from all the identical issues you are able to do with code to do this. With one thing like Google docs,

Bob Ducharme 00:23:55 I imply, I feel it’s nice for inner documentation, however I all the time thought the worst case with documentation. Some little corporations will do is that they create a Phrase file, proper? Right here’s a 5-page Phrase file about how one can use the product. After which when a brand new launch comes, they’ll pull up their Phrase file and revise, a few of it. They usually’ll put, I hate after they put the Phrase remaining within the file identify. Perhaps generate a PDF from that, or perhaps even give individuals the Phrase file, which is a reasonably amateurish option to do it. And Google docs is nice for thus many issues, however the versioning of it in tying that to launch variations of the software program, I feel you’re a lot better off utilizing the instruments {that a} software program firm already has in place to do this. To do Git or Bitbucket or no matter, to maintain monitor of the items and the connection of the items and the connection of these items to the releases. So it’s typically for a tech author to be taught the archana of Git might be irritating, nevertheless it’s not such as you’re doing lots of rebasing and so forth with the documentation. So that you don’t must get that far into the troublesome Git weeds, in my expertise up to now.

Nikhil Krishna 00:25:00 Yeah. That’s a terrific level. And simply, so that you talked about additionally earlier about publishing the doc as a HTML web site. So, one of many issues I’ve seen, particularly within the open-source world is the rise of those particular issues like learn the tops or a particular sort of web site software program as a service platforms, proper? The place Git books, learn the docs, et cetera, the place they really deal with the internet hosting and publication they usually even have, issues like looking your documentation throughout numerous variations, et cetera. So, from that perspective, do you’ve got a course of on a software chain from constructing documentation from the purpose of, okay, I’ve now entered the content material. So, I do know that is the content material that I want to publish. After which sort of like, is that like an excellent software chain that you just’ve used, or perhaps you may discuss just a little bit about your expertise with older instruments and stuff like that. However sometimes what’s the software chain that one sometimes makes use of these days to generate these web sites and the CSS and HTML and all that?

Bob Ducharme 00:26:23 I feel a few of the hottest instruments now are mainly instruments for technology of static web sites which are typically specialised for documentation. So, for instance, the place I’m now, and it would in my final place that I held earlier than we use Sphinx. With Sphinx you’re creating the precise content material in restructured texts. It’s a type of markdown descendants. So Astros on both aspect, to daring or italics and so forth, however then you may nonetheless have your CSS and have the construction to indicate that these six pages right here, I need to create a Desk of Contents right here that has these six on this order. And that each one will get automated the technology of all that HTML. And when you’ve got these recordsdata like this, the RST and the CSS and different issues like that, it makes it simpler to include it right into a model management, into Git or one thing like that.

Bob Ducharme 00:27:18 Then it might be for those who have been like revising Phrase recordsdata time and again. So it may be a part of the software program documentation software chain. After which they’ll have a go course of and a few locations will combine it extra deeply or not into the software program construct course of. However as a part of a launch you need to be sure to’re getting the three factors stuff. 3.2 stuff, 3.2 product and three.2 code all in the identical place. So it typically is tightly built-in there. So I’ve discovered that very helpful. And it’s additionally due to its relation to markdown. It’s simpler for builders are used to that. In order that they don’t thoughts writing in that if I may again off and go into just a little historical past again within the, I suppose within the Nineteen Eighties, there have been when computerized typesetting was turning into a giant factor. These corporations would say, yeah, you may ship recordsdata with codes of the way you need your books laid out and the place you need the fonts and all that.

Bob Ducharme 00:28:13 And in these days it may have been delivered on tape for all I do know. So you set in these codes, would you need to have these codes once you need a subhead and these codes for bullets and so forth, however completely different competing corporations doing that. They’d their very own units of codes and a few individuals, I feel some at IBM particularly, I do know for positive, however another locations as effectively, they stated, wait a minute, we don’t need to tie up all of our, have all of our documentation written utilizing your proprietary codes. We need to have extra flexibility. So, they got here up with a, what grew to become an ISO commonplace. SGML a option to outline the construction of a doc after which to make use of that construction definition to say, you already know, let’s say you’re going to have a cookbook. I need to create one thing it’s going to be a number of recipes.

Bob Ducharme 00:28:57 And a recipe’s title, after which it’s an inventory of elements and an inventory of steps. After which there’s going to be an element what number of it serves. So with this SGML you can outline a construction like this after which create the paperwork on this case, recipes, after which automate the checking of people who construction confined to, does it comply with the construction that I outlined? And for those who, for those who be aware it follows a construction, you can automate much more. You possibly can then flip, and that is within the early days of multimedia getting past paper. I’m going to show it into on-line, assist. I’m going to show into CD ROMs. I’m going to show into HTML. And so I obtained concerned in HTML and I might go to the conferences and I obtained to know a few of the individuals who did it.

Bob Ducharme 00:29:35 And a few of them realized SGML and a few of the software program was very costly doing this. Among the SGML was very difficult. So, a few of these individuals obtained collectively and thought we have to create a less complicated, simpler model of SGML. One thing that wouldn’t take a lot computing energy, one thing that might be parsed with a program that’s you may simply obtain over the web with this new language, Solar Microsystems has referred to as Java. In order that was 90’s, I suppose? So, they have been engaged on the simplified model of SGML. They first, the primary unique working title for it was Net SGML, not as catchy. After which somebody considered a catchier identify, XML. And that’s the place XML comes from. It was a simplified model of SGML. So, lots of the software chains SGML when it was invented for this, that’s what locations like Boeing and huge protection contractors to doc the engine components they have been pondering again then, that documentation, we must always deal with it like software program by way of breaking it down into elements.

Bob Ducharme 00:30:36 If this subsystem of this engine can also be used on different engines as effectively, we must always have the ability to write up how one can clear, how one can restore this sub system after which take that write up and add it to the documentation for the opposite engines as effectively. So these have been a few of the early strikes towards making documentation componentize, similar to software program in order that it might be blended and matched and used for various merchandise. And there could be the software chains for SGML and later XML to do what I used to be saying about syncs now that you’d have your CSS right here you’d have instruments for producing the HTML from there, or the web assist or the CD rom. Builders didn’t like dealing instantly with the XML as a lot, markdowns are just a little easier. And there have been instruments to be just a little extra gooey-ish, just a little look, just a little extra like WORD that will nonetheless output the suitable XML, however typically these might be costly.

Bob Ducharme 00:31:30 In order that’s one other form of lineage of the software chain for creating software program documentation, {hardware}, documentation is XML and associated instruments. Individuals don’t understand that that’s what XML was for as a result of when it was XML was first invented, it was across the time of the.com increase. And with the.com increase, early 2000’s. There have been individuals, you already know, we’re going to have seamless e-commerce and have this laptop talk with that different one throughout the online to ship the orders and reply to the orders, however sending and responding to those orders, they needed to ship these batches of information that didn’t essentially match into CSV. They’d have extra difficult buildings than that. In order that they noticed this XML factor from the W3C. We will outline our personal buildings. You realize, right here’s the start of a order, right here’s the tip, right here’s the deal with, right here’s the listing of things being ordered and so forth. In order that they began utilizing XML for that, to do that E-commerce. Mainly the sort of issues persons are utilizing Jason for now. They began utilizing it and thought, that is excellent. After which they determined, no, this isn’t excellent in any respect. That the information typing system is bizarre and whoever designed it did a horrible job. Nicely, they didn’t understand that whoever designed XML was not designing it for the makes use of they have been placing it for. For dealing with arbitrary handfuls of information about transactions forwards and backwards.

Nikhil Krishna 00:33:28 Simply to shortly simply bounce in on over there. So, I keep in mind that we went down this complete path with XML in regards to the net standing, the Ws star, and the entire set of VEP service X quantity of requirements. I feel one of many, perhaps the issues that sort of led to the adoption of Json and the requirements like that was the truth that you’ve got all the sediment right here how, what the doc must be like. However I additionally keep in mind at the moment, there was this competing, talking for documentation, there was this different factor referred to as RDF, proper? And I used to be simply questioning, was that really one thing that would have, if appropriately championed being one thing that sort of to go over the documentation aspect of issues that XML sort of was meant to have, or meant to be for?

Bob Ducharme 00:34:25 No RDF is nice at metadata paperwork, however to have a collection of paragraphs with sentences the place there’s inline factor in the midst of a sentence, I’ve a hyperlink, I’ve a bolded time period, RDF will not be good for that. Our RDF is about decreasing information down to those three components statements referred to as triples. So I can say worker 38 has a rent date of January 1st, worker 38 has the final identify of Smith. After which the flexibleness that RDF provides you over one thing like a relational database permits a a number of new issues, together with the flexibility to mixture information from completely different sources and issues like that. And I imply, I may go on and on about RDF, however for linear

Nikhil Krishna 00:35:07 So it does extra of that one thing that XML was making an attempt to goal to be that what the web site was maybe a greater means of doing it.

Bob Ducharme 00:35:21 You realize for one thing like Json, you’re higher off, I feel. With RDF, the metadata, when you’ve got particularly lots of, within the area of digital humanities and lots of publishers, they’ve content material from a number of completely different locations they usually need to preserve monitor of the content material and that content material, in these various things may have completely different bits of metadata, however typically they’re associated, though they’re completely different as a result of from this requirements, physique or that one, and so mapping between the requirements of the dig after which question throughout all their metadata for a spread of thess, RDS actually good for that. However not for the content material itself, the form of narrative content material of paragraphs and bulleted and numbered lists. We may do complete forged on RDF.

Nikhil Krishna 00:36:00 Yeah. So to come back again just a little bit on again to our technical documentation matter, one of many issues that I’ve seen, you talked about utilizing swings and the software chains like that. And we additionally mentioned a few of the older instruments like SGML and XML, nevertheless it appeared to be typically that relying on the kind of documentation, a few of these is extra automatable and others are much less, proper? So, for instance, we talked about earlier in what sort of technical documentation must be generated. We talked about FAQ’s tutorials, high-level technical paperwork, which clarify issues to non-technical individuals. However on the similar time, in case you have one thing like a Jess on API or HPP API, we even have instruments that like Swagger, which you’ll be able to simply discover that the, the specs or the API itself, in some instances sort of generates the documentation out of it, proper?

Nikhil Krishna 00:37:10 It’s nearly like you may take a look at the sorts of the assorted response requests and that sort of create a doc that means that you can, in some instances, even create pattern instance requests and responses that you should use for testing. However I typically get the sensation that, okay, that’s once more, too low degree. The place do you see the stability between the 2 must be? And the way a lot of the documentation that’s generated for a software program undertaking might be generated like that? And the way a lot of it’s nonetheless one thing that you just need to just remember to write within the correct method?

Bob Ducharme 00:37:52 That’s an excellent query. I feel, like I discussed one thing like a tutorial, you actually need to think twice in regards to the order you’re going to elucidate issues in what you’ve got the individual do of the three buckets. I discussed of tutorials, reference guides and person guides. With reference guides, it may be just a little extra automated like with Swagger, I’ve used it however I can’t keep in mind the identify. Is that, was that the software you talked about that may pull issues out of APIs and generator?

Nikhil Krishna 00:38:20 Yeah. So spider is mainly a part of the open MPI. I feel it’s referred to as the Json API documentation tooling and what it does is it seems at Json’s paperwork and sort of generates the request agenda web-based documentation, which has which particulars on all of the lists of all of the attributes properties after which the sorts of it. Which isÖ

Bob Ducharme 00:38:47 And I imagine it’ll pull out

Nikhil Krishna 00:38:50 Yeah, it pulls out a few of the feedback as effectively from the entrance, from the operate. So you will get a excessive degree, two line description of what the API does, however then that is dependent upon how effectively, if

Bob Ducharme 00:39:02 Precisely, and, and that’s rubbish in rubbish out. I imply, that’s a software that may undergo and pull out and see, oh, this operate takes three parameters and the parameters are presupposed to be of those sorts. And it returns one thing of this kind. That’s good to automate the pulling of all that and the enumeration of it, however this, the doc strings, how typically have we seen doc strings? So simply clarify what we wished to elucidate. So, and that may be a tech author operate to, to overview that documentation after which perhaps create some tickets and say, hey, you return and revise that doc string to elucidate that higher. One in all my pet peeves is whether or not it’s explaining the fields on a dialog field or parameter being handed to a operate. If we are saying right here’s a parameter referred to as Fu and the documentation says, enter the Fu worth there. And I’m pondering, okay, however what’s Fu? What function does Fu play on this software? And what sort of issues may I put there? So the reason that goes in there, instruments like that, they’re like bare instruments. It’s nice how they will pull every little thing collectively after which create the factor you’re searching for. However the issues they’re pulling collectively must have some high quality in them and typically they will help level to which components have to be up to date, however nonetheless it’s rubbish in rubbish out.

Nikhil Krishna 00:40:22 Proper. So now that you just talked about that he had talked about maintaining and utilizing the identical Git tooling and the movement tooling and making an attempt to maintain the documentation variations the identical because the software program. In order each portion of software program, you additionally purchased the model of documentation that sort of keep that. So mainly we could, if we sort of, from a course of perspective, say being self-aware as a software program engineer, we mainly approached doc strings or feedback. And we sort of write a correct clarification for each operate. And mainly attempt to use that as documentation. Do you assume that theoretically, it’s attainable to sort of combine that in. Do you continue to really feel that there’s a separate place, require a separate folder or perhaps a separate undertaking inside your Git repository that it is best to preserve a separate viewpoint, separate perspective, or a separate kind of documentation?

Bob Ducharme 00:41:29 This actually will get again, I feel, to the excellence between reference guides and person guides. Reference guides that’s all reference information stuff. You realize, you need to listing every little thing. I imply, I feel when somebody seems at a product they usually see some unusual icon or menu selection and assume, effectively, what’s that for? The reference information is the place they might look it as much as discover it out. In truth, with a graphical person interface, and this may be troublesome, however I feel it’s essential. Each software tip must be, if there’s some unusual icon, you don’t know what it means, however you mouse over it and also you see some software tip. That software tip must be one thing that the person can search on within the reference information. And, I’ve labored locations the place I needed to inform the client builders earlier than every new launch, which software ideas obtained modified?

Bob Ducharme 00:42:11 I need to have the ability to identify all of the software ideas within the documentation, as a result of that’s the hook for individuals to seek out out what the icon is for. So lots of the reference guides for not just for technical issues like APIs, however even for the gooey, as a result of for the graphical person interface to elucidate every little thing they see, they need to have the ability to lookup what that’s. Alternatively, some extent I wished to deliver up about person guides is that effectively, I discussed how, once I wrote up Desk of Contents for an XSLT ebook, I didn’t use any XSLT phrases. I talked in regards to the duties to do. If let’s say, for instance, your product has a part to develop a schema and it’s referred to as Schema Wiz, okay? And also you’re going to doc that, to me if the person information has a header referred to as Getting Began with Schema Wiz, that’s not an excellent title.

Bob Ducharme 00:43:00 I imply, I need to see titles like Making a New Schema, Revising an Previous Schema, Deleting Schemas. Naming the duties that have to be completed versus utilizing the phrases you made up on your product as a part of the motive force of the person information. So I suppose to get again to your query about a spot for one thing separate from the, the listing of issues, that’s the place the person guides go. To one thing organized by the duties they need to do, versus one thing that’s organized by the product itself, being organized by the product itself continues to be essential as a result of that’s the place they see one thing on the product that, that’s the place they go the reference information to see what is that this factor for? What good will this do for me? So, I suppose to simplify, to getting again to your unique query, that’s the distinction to me between reference guides and person guides.

Nikhil Krishna 00:43:48 Proper. So once more, these days mainly there may be this concept of an X Esco philosophy, proper? So, you’ve got dev sec ops documented. So, we now have safety as code configuration, Esco X, one thing else. That is philosophy that every little thing sort of begins turning into encode. We sort of been discussing how shut documentation is and our how they’re with code, so ought to we be treating, approaching our documentation as code and sort of fully have, not simply the portion management, have software program processes for it. So, we are able to have like who to request for documentation, the ICD for different documentation. We’ve like a overview course of. We’ve like, we now have documentation opinions. What do you consider this specific? What’s your opinion on this?

Bob Ducharme 00:44:51 I imply, I agree with it. I feel that treating it as code, allows you to benefit from all these instruments that you’ve got that you have already got to work along with your code. So, for instance with opinions, overview of documentation, like code opinions, lots of corporations, I write one thing I would like it reviewed. I created a journal ticket, to assign somebody to overview it. After which we are saying this, this function is held up till somebody does the overview, similar to when somebody’s reviewing some C code that was written. So, I feel that treating it as code has the benefit of letting you benefit from all these instruments. We simply, why the old school means of making a WORD file to have the documentation there. It doesn’t allow you to benefit from these instruments and issues. So, utilizing the software set is the benefit you get from treating it as code. So, I feel that’s been inspired in lots of locations proper right down to the usage of JIRA tickets to assign documentation duties.

Nikhil Krishna 00:45:46 Okay. So then if provided that proper, that in smaller corporations, it is usually typically the function of whoever’s doing the software program documentation to additionally develop issues for advertising and marketing, proper? And for Gross sales. So, then you’ve got like in startup, you may need the identical technical author and even software program developer, for instance, being approached by the advertising and marketing division and saying, Hey, okay, we wish you to write-up one thing about this specific function that we are able to publish or share with the e-mail publication, for instance. Do you assume the talents required for this sort of writing, writing advertising and marketing content material and writing gross sales content material, how related is that? Or how completely different is it from writing technical documentation?

Bob Ducharme 00:46:42 I feel it’s very related as a result of, particularly once you’re writing technical documentation, issues like tutorials, as I discussed, and even launch notes, I thought-about to primarily be advertising and marketing paperwork as a result of with each the tutorial and launch notes, what you’re seeing is take a look at this cool stuff. Isn’t this nice? Right here’s this factor so that you can use. So I consider them as, as advertising and marketing documentation. Advertising communications is a option to promote issues. To say, what are the good issues in regards to the product and why individuals must be serious about utilizing it. Inside a corporation you’re typically working with the advertising and marketing individuals. You develop into the tech editor, they may begin throwing the issues that make your product cool, perhaps related to buzzwords that they wish to throw round, however don’t perceive, that’s fairly widespread. So making that technical documentation extra, making the advertising and marketing communications extra technically correct, I feel is a giant a part of that. They usually’re normally comfortable to have you ever proper? Or a few locations I’ve labored the place they’ll have a software program developer write a weblog entry. And then you definitely, because the tech author, rearrange it a bit to make it extra, user-friendly not solely to clients, however to potential clients. I imply, individuals who simply got here throughout your weblog and are much more on technical, however they will get perhaps shopping for the product in order that the technical author is form of coordinating between builders and advertising and marketing individuals to assist create new weblog entries.

Nikhil Krishna 00:48:09 So we must also embrace this class into our thought of documentation as code and sort of subjected to the identical sort of processes. Do you assume that that’s to work? So, is that one thing that’s troublesome to do once you begin involving third events like gross sales and advertising and marketing and all of these individuals who is probably not aware of it?

Bob Ducharme 00:48:36 Yeah, in all probability not the identical processes as a result of, you already know, gross sales and advertising and marketing individuals it’s, you already know, assigning them tickets and having them verify issues into Git, it is likely to be a bit an excessive amount of to ask for. However I feel serving to them to coordinate the content material itself to ensure that it’s technically correct, however well-written, that each one is, I feel very helpful they usually’re in all probability going to have their very own instruments. You realize, they is likely to be creating PowerPoint displays they usually need your assist with that or Phrase recordsdata that they will flip into PDF. So, they’re going to have their very own processes and the developer processes of utilizing Git and so forth might be going to be over their heads. However, you already know, you’re the liaison between them, between the advertising and marketing individuals and the builders. It’s your job as a tech author to translate the technical stuff to the non-technical individuals. So that’s an attention-grabbing place to assist apply that. To serving to with the advertising and marketing.

Nikhil Krishna 00:49:27 Superior. So, Bob I feel we’ve sort of reached the tip of what I had in thoughts. In our dialog up to now, we’ve talked about software program documentation from the angle of a reference manuals and person manuals and guides and issues like that. There’s additionally, particularly for those who’re writing, for those who’re a part of a software program undertaking, that’s a reasonably substantial shock software program product you is likely to be requested, effectively, can we create a ebook grant? Can we create some sort of substantial artifact out of it? Proper? So perhaps we publish a ebook in regards to the undertaking. Is that the identical as, or just like, by way of course of, to creating technical documentation? Do you assume a ebook is an effective means of writing a few software program product that retains altering and retains evolving, simply a few questions?

Bob Ducharme 00:50:27 Nicely, you can, I imply the person information materials you’ve got, that that might be an output format. There are methods to simply flip that into a tough copy ebook, however I feel a associated situation a few ebook is that some individuals will we’ll see, okay, O’Reilly has a bunch of books about Oracle merchandise. You realize, that will be cool if there was an O’Reilly ebook about our product or Manning or one of many large laptop publishers, some workplaces the place individuals thought, oh, wouldn’t that be cool? And writing a separate ebook to go together with a writer. I imply, some publishers will work with you to do a brief ebook that you could then give away, however you already know, that’s going to price you cash, however to put in writing an entire ebook about one thing that may be a form of separate entity from a separate writer, it’s enjoyable when it’s completed, nevertheless it’s much more work than individuals understand.

Bob Ducharme 00:51:13 And you already know, we have been speaking earlier about one of many points of creating movies is you set an enormous quantity of labor in one thing that might be out of date six months later. For those who’re going to place 5 or 600 hours into writing a ebook that’s going to be, that would probably be out of date a yr later, a yr and a half later. And that’s an essential factor to consider the sources that go into the creation of the ebook. And once I’ve written books, they’ve normally been about requirements as a result of requirements transfer extra slowly of their upgrades than merchandise from corporations. So, for those who’re writing about launch 3.2, when 3.5 is out, individuals aren’t going to look too exhausting at your ebook and it may be much more, some individuals will they’ll assume like, effectively it takes me half an hour to put in writing a web page.

Bob Ducharme 00:51:59 So a 300-page ebook that will take me 150 hours and that’s not the way it works. You realize, one of many causes you can write that web page in half an hour is since you already had that web page’s value of content material in your head, all organized. There’s much more work to do to prepare the content material for 300 pages. Secondly, even for those who may write 300 pages in 150 hours, that’s simply your first draft. It’s obtained to undergo extra drafts simply to enhance the writing to ensure it’s technically appropriate. Plus, you’re going to have lots of analysis to do. Some individuals assume, oh, effectively, we may do it in half the time if two individuals wrote it collectively, nevertheless it’s going to be extra like 70% of the time as a result of it’s important to coordinate what you’re doing. After which as soon as the factor will get upgraded your ebook goes to look old-fashioned. So there are some highlights to writing a ebook about your software program to be revealed by a writer that — I used to be going to say places issues in bookstores. We don’t see that a lot, however — places issues on Amazon the place individuals can purchase the ebook, however it may be much more work and it’s important to contemplate how shortly it’ll develop into out of date. After you have an improve or two, it’s all this work you probably did as already historical past. Does that deal with what you have been asking? I used to be sort of rambling there.

Nikhil Krishna 00:53:07 I feel that’s a terrific overview of a few of the challenges of ebook writing, and I’m positive not the least of it is usually the completely different course of that the ebook publishers may need. Proper? It may not be the identical factor that you just’re used to following along with your technical articles the place you in all probability editorial oversight as effectively. However yeah, I feel that’s, that’s a terrific level to sort of finish this podcast. I simply wished to ask if listeners would be taught to comply with or contact you, if there are, perhaps you’d like to speak about a few of the issues that you just’re engaged on proper now, that is your likelihood.

Bob Ducharme 00:53:50 If individuals need to contact me on Twitter, I’m @Bob DC, B O B D C. And likewise I did handle to get a few years in the past, the area identify, BobDC.com. So, you will discover out extra in regards to the books I’ve written and that’s additionally the place I’ve my weblog. So there are a number of, I can ship you a hyperlink to place within the present notes of a collection of weblog posts. I did a number of years in the past, actually about writing documentation, about a few of these points we’ve lined and another issues to remember.

Nikhil Krishna 00:54:15 Superior. We will certainly add that to the present notes, and I suppose all meaning is thanks. Thanks, Bob. This has been a reasonably participating dialog. I feel this it’ll be very invaluable to our listeners. Thanks for spending the time with us.

Bob Ducharme 00:54:33 Nicely thanks for having me. It’s going to be enjoyable driving round in my automotive, listening to a podcast the place I’m the one speaking. I’m positive you’re used to that by now, nevertheless it’s been lots of enjoyable. And I like speaking about these items.

Nikhil Krishna 00:54:43 Thanks Bob. [End of Audio]