[00:00:00.120] - Liz Fraley

Welcome to the TC Dojo from Single-Sourcing Solutions. TC Dojo is a techcomm community that is driven by you. Tell us what you want to learn. You choose the topics and we find the experts. In the TC Dojo open session today, we have Clarence Cromwell. Clarence is a technical writer at Synopsys. He is also one of those people who works hard in his community. He's been an STC chapter President, organized programs, and currently organizes for Write The Docs in the San Francisco Bay Area.

[00:00:31.120] - Liz Fraley

He's a voice I listen to when I'm looking for ideas and talking about trends, and I'm grateful he could be here in the Dojo with us today. Now, Clarence says to save your questions until the end, but be sure to type them in when you think of them so you don't forget what you wanted to ask. All right, I will stop the share, pass it to you and it will be all yours. Hit the share button. 

[00:00:56.300] - Clarence Cromwell

Let's just get that. I was an STC chapter secretary. 

[00:01:03.140] - Liz Fraley

I knew you were an officer and you've always worked really, really hard. Let's see, there's a green button in the bottom ribbon, you should be... 

[00:01:12.030] - Clarence Cromwell

Oh, I'm still, yeah I was selecting a desktop and you get to see the rough cut.

[00:01:23.150] - Clarence Cromwell

OK, so Templates for API Docs. So I'm going to mention that this information I'm presenting, I have developed in conjunction with The Good Docs project, which is an open-source project for improving documentation. And templates, are just one aspect of what they do. But it was the first, it was sort of the first and biggest thing in the Good Docs project, and that's kind of my only involvement with them. So for maybe a year and a half, me and other people over there have been working on templates for documentation.

[00:02:02.140] - Clarence Cromwell

So what I'm presenting is sort of my piece of that. So the first question, the best way to jump into this is the first question we said we would answer today, which is Minimum Viable Documentation and what is that? And a really quick definition that I that I've started with is the least amount of documentation that will get the job done.

[00:02:32.120] - Clarence Cromwell

And this is really interesting because not very much documentation, if you think about it, isn't that awesome because one of the biggest complaints people have about documentation is what's missing. So less isn't necessarily more. And if you think about it for very long, the viable is sort of the key word and, you end up focusing on what really makes documentation viable. What makes it work and probably the best answer to that is helping people get... People accomplish what they want to get done, with the least amount of pain and frustration.

[00:03:12.040] - Clarence Cromwell

And then once you focus on that, you realize how complicated it really is to have minimum viable documentation, because you have to, you have to really be helpful. So you have to know that you're helping users accomplish what they want to do. And that's not easy. And so, moving in that direction, I kind of work towards, as I worked on this project, worked towards an idealized definition of what minimum viable documentation should do and what it should accomplish.

[00:03:49.040] - Clarence Cromwell

So you know, basically, what if 80 percent of your users don't have pain and frustration? And what if, out of the rest, most everybody doesn't have very much pain and frustration? That's maybe better than a lot of documentation is why I go to this, and especially in the beginning when you're working on your documentation and maybe users aren't that happy. I think when you're when you're trying to get something off the ground. I think this is sort of like an attainable goal and something that we don't always hit and it's kind of hard to do perfectly every time.

[00:04:32.120] - Clarence Cromwell

If you've done a lot of documentation, you probably realize that a lot of the time we're not getting this right. So then the question is like, well you know how do you do that right? So I'll jump, so I'm going to jump to what the templates are like, the final product of the templates, and then explain how I got to these and how they're supposed to address this pain-free environment for users.

[00:05:00.590] - Clarence Cromwell

This is very simple and it might look familiar. These documents types might look familiar to people who've done a lot of documentation. Anyway. So I don't assume that people call these the same things I call them, or that everyone uses the same documents. Or maybe I don't assume that everyone has a lot of experience. Maybe somebody is new and they just want to listen in. So I'm going to describe what I'm what these are. But this isn't the... This is just sort of to get started.

[00:05:34.510] - Clarence Cromwell

The... When I'm talking about an API reference, I mean, the document that lists all your API endpoints in a service. So if your API is a collection of addresses where you can send a request and get a reply, that's an answer from the API service. Your reference is just a listing of all those addresses, all the commands you can send to them, and an explanation of the replies that you would get back from any one of those. And a quickstart is a set of steps that tell you how to accomplish something, but specifically, it's the one you use in the beginning when you start using the service. You want to know what it does, and you wonder how it works, and you want to get up to speed. And so it's a really quick set of steps saying "here's how to" probably starting with how to set up an account or authenticate or you know, get into the service. Here's how to do the main thing that it does you know, and get the results you want to get.

[00:06:43.080] - Clarence Cromwell

A combination of "here's how to begin using it" and "let us show you what's great about it." And then the overview, which I don't know if as many people use, but I was sort of thought this was mandatory. Overview is just a one-pager that says, what does this service do? How does it work? Why would I want to use it? Sort of like, what's it for? It's like the "so what" question? Addressing the "so what" question is always handy.

[00:07:18.680] - Clarence Cromwell

So these are the three types, and the... It's interesting that I ended up with these because I, I kind of got to these in two different ways. Which is one reason I want to explain, like what these are and why they're here. I have three of these and the point is, I don't have just one, I don't have just the reference and I don't have these three plus one more, because the path that we ended up exploring brought us to these three documents. So here's why. And we've sort of two different things pointed this. So the first thing that happened is doing research into journal articles and some Internet sites. What makes API documentation work? There's been plenty of research going back even into the 80s and 90s about what makes APIs usable.

[00:08:28.340] - Clarence Cromwell

What do developers hate about APIs and API documentation? What do they prefer to see? Different people look at this question from different angles and so digging through that, I sort of compiled information about what are the pain points? What are the difficult parts of using documentation? Going in the direction of if we want to make the documentation painless, what areas do we focus on to eliminate most of the trouble? And so this is how the focus got to be in the beginning, this is how the focus got to be on these three documents.

[00:09:10.710] - Clarence Cromwell

Turns out that people will quit. So I always use the term quitters, you'll have quitters if you don't have a quickstart. I think nobody ever talks about a lack of an API reference because it just wouldn't be possible. There's always is one. It's a question of quality. But I've seen APIs with no quickstart, you could also call it a tutorial. And I think you could lose... I might be pulling up the wrong number, something like a quarter or a third of potential users will just walk away if there's no quickstart.

[00:09:51.180] - Clarence Cromwell

And the overview has... It's maybe a smaller group, but I don't remember exactly the size, but I'd say a significant number of people might not start if they can't see that explanation. Because that group of people wants to really understand what they're dealing with before they commit time to jump in and do the nitty-gritty details. They want the big picture or they're out.

[00:10:10.640] - Clarence Cromwell

So. These three document types sort of emerged from looking at research into like what do people want and what do they not want? And then so here's where it gets interesting. When I looked at these and I realized what I had, I knew this was the right thing, I knew this was the right set of documents and that I had everything. Because I realized that I have a reference topic, a task and some conceptual information. And I thought back to when I was learning to be a technical writer in the certificate program at Berkeley Extension, and I learned that these three categories are sort of the three types of information that you classify things into and keep separate.

[00:11:06.810] - Clarence Cromwell

So like on the first or second evening of class, my professor walks into the classroom and she has tremendous stack of books that she's carrying like this. And she starts to put a book down in front of everybody, these giant thick books. And there's you know 20 or 30 students, and the book she puts in front of me is a cookbook. And we're all looking at cookbooks and she says... The professor was Joanna Bujes, whose my manager now.

[00:11:39.970] - Clarence Cromwell

So she's great at teaching this. She says, OK, we're going to talk about documentation today, but we're going to start by looking at cookbooks. And you know, it's a great analogy because the recipe is a set of steps that lets you accomplish something. When you read a good cookbook like The Joy of Cooking, which is like my favorite cookbook,

[00:12:00.640] - Clarence Cromwell

there's an overview at the beginning of each chapter. There's a fabulous chapter on how to select cuts of meat, how to store them, and things like this. Same thing with produce, same thing with baking. I'm not really the baker, but it's there. And there's... So you have your tasks, you have conceptual information and there's a little bit of reference, I never maybe I never use the reference I had to go check my Joy of Cooking but I...

[00:12:33.550] - Clarence Cromwell

So I looked in the back yesterday as I was putting this all together. There's a really nice table about how long you need to blanch your vegetables for how many minutes and depending on if you're eating them or just blanching them quick to freeze them. And this was a nice table about how many pounds of fruit it takes to make a quart jar if you're canning fruit. And actually, like we were putting up, we were putting away pears just a little while ago and I was thinking, wow, I could have used that because I would have known how many quart jars of pears I... How many quart jars I was going to have of pears.

[00:13:08.140] - Clarence Cromwell

And what I did was I just took down all the jars anyway but, so, good stuff.

[00:13:14.410] - Clarence Cromwell

So I guess the point is, this is a natural way of organizing information, not sort of like an artificial system foisted on us by DITA, because that's strongly associated with DITA. But when you're trying to explain to people how to do things. This is organic and natural to go Reference, Task, Concept. Anyway, the long and short of it, dividing the information these three ways, separating it into these categories is effective because when I'm in the quickstart, the overview information and the reference information aren't mixed in.

[00:13:58.310] - Clarence Cromwell

And you know when I'm looking for reference, I don't have steps mixed in or overview mixed in. They're not in the way, and at the same time, when I'm trying to find something, I could find it because I know where it is. And that's sort of the basic nuts and bolts of it. So on the information architecture level, having these three categories works. People don't quit and they can find what they want. Because of what's there and then there's a second level to these templates where once you have the right documents.

[00:14:33.910] - Clarence Cromwell

The content in these templates tells you some things about... There's kind of a bulleted checklist and I'll have links to the templates later, but there's kind of a bulleted checklist to make sure that the templates describe, that your documentation has everything it should have in it and it answers the right questions in the right way. And they're sort of a ton of findings that I sort of dredged up from research, but what I want to share since time is limited and there are a lot of small points, I'll bring up the two most important content things that the templates point you to, because these are the things that people complain about the most.

[00:15:21.630] - Clarence Cromwell

If you read through, at all read through like journal articles or just read web pages about how to have good API documentation, here's what you're going to see. Two major things. Have code examples that work, and have copious comments following after them to explain to people how to use the code examples. There are people who read your documentation and then try to follow it or try to follow it from top to bottom, but that's one type of user.

[00:15:58.170] - Clarence Cromwell

And then the other type of user is the cut and paste user who... See every...They look at your page and they think, oh, every code example is a step, so I'll just go cut - paste, cut - paste, cut - paste. And people just, some people are just doers they cut and paste and if it doesn't work, then they go back and they expect some comments right under there to maybe explain why it might not be working. 

[00:16:22.610] - Clarence Cromwell

And if you address, if you want to address both kinds of users, you need to have very good code examples with lots of, well, lots of comments with effective comments close after, and that's sort of implies things outside of writing the document, like maybe testing it yourself, and you know maybe if you're going to cut and paste and work all the way through this process, maybe there's bigger things like if this tool does something to a file, you need an example file, etc. That's sort of larger than this. But general idea being, that people can just use the examples and get help, the help that they need right there inside of that step.

[00:17:07.380] - Clarence Cromwell

Everything they need to complete the step, that's number one. Big area number two is the completeness of reference documentation and I say this is a bigger deal than most people think because, anybody who either builds APIs or has worked on API documentation knows that when you list all your attributes, you're going to provide the same four pieces of information. It's got this thing as a name, it has a data type, it has if it's required or not, it has a description. And people will look at the checklist and say yeah, but we know that and Swagger generates the stuff. And the thing is, Swagger doesn't automatically generate the description, or people don't automatically write good descriptions, and when you have maybe hundreds of endpoints or hundreds of attributes, you know, one thing that's out of place is kind of like a pothole on the Autobahn.

[00:18:26.200] - Clarence Cromwell

So when people are going smoothly and they come to this pothole that completely stops their progress, they don't remember the ninety-nine miles of smooth pavement, they remember the one thing that was a shock to their progress. And the sort of... the factor that, when many people complain about documentation, it's just the incompleteness or not usableness of reference information. And for example, when you were going to go into more detail when you're putting together a YAML file for Swagger documentation, your attributes will appear as you... in the documentation as the written things that are required will be required.

[00:19:18.210] - Clarence Cromwell

In your YAML file, you're not required to render a description. Everything will happen if you don't provide a description or if you provide empty quotation marks. I think of those as the international symbol for like we'll get to this description later. But if you just have quotation marks there, the user won't know what to do and, they won't proceed past that point. There are places in Swagger like the description of a service, and description of a group of endpoints, and the description of each attribute where you sort of have to make sure that the user gets what they want. So like in the reference template, it calls for explaining what an attribute is for when a person might actually want to use that attribute. And if there are, for example, if there are only a handful of acceptable values, what are they? And if there are only a handful of acceptable values, it should be clear in which situation do I use which one of those? The same thing goes for the request and the response. So in the response, this I've seen complaints on almost every API, I've looked at eventually.

[00:20:54.530] - Clarence Cromwell

When users see the response, they want to know, they want a description to tell them what it is so they know what they're supposed to use it for. And I've seen at least one user saying, what is this for? What why don't you tell me why you're giving this to me? What am I supposed to do with it? So if you keep that in mind, when you're looking at your API reference documentation and keep in mind that people want that level of detail on every endpoint, every property and attribute.

[00:21:31.790] - Clarence Cromwell

So 80 to 90 percent of happy users just have to make sure you have all three of those documents, provide working examples with comments and be detailed about your reference documentation. And that's kind of the recipe to get there, I'm looking at my notecards because I didn't want to forget anything. So I'm going to distribute or I think I hope Elizabeth is going to help me distribute PDF of these afterwards. So that I have links to these three templates as they are, actually, I could share one of these really quick if we have time on screen.

[00:22:23.210] - Clarence Cromwell

I wanted to mention you can use these for new documentation, which is the context that a lot of... That some people think of or maybe everyone thinks of first, but using these templates for existing documentation, I think is actually a much more needed and common case. Just, for example, when it seems like whenever you get the first technical writer on a project or maybe just when you get on a project as a technical writer, there's never an overview.

[00:22:53.340] - Clarence Cromwell

And frequently, once you get it, dig into the project deep enough. You can make a big impact just by writing an overview to explain you know, what it is and why people might need to use it. And I wanted to mention that these three templates are minimum viable documentation, but they're not anywhere close to the maximum. So I know that. You know, if you come on to a project and add a quickstart and an overview. Very soon you're going to be adding workflows after that, because there'll be other operations, like there'll be advanced things that you just want to do and it'll just go from there.

[00:23:33.070] - Clarence Cromwell

But you frequently need to come on to a project that seems kind of mature and still add something to have the minimum. Or you, if you start a project, you'll have this in the beginning and you'll...it'll just grow from there. So it's very, it's not a rigid framework. It's just a set of guidelines and this is the last slide, this is some links to The Good Docs project where you can see these three templates and more templates for other kinds of projects.

[00:24:09.680] - Clarence Cromwell

I don't know if I mentioned it, but you could contribute projects, sorry templates there. If you're doing something and you look for a template, you don't see one there, you can always try to build the template and contribute it. Get some people to work on the template with you so, all that you have to do is go there and talk to the folks at the Good Docs project. They also have a Slack group, GitHub repo.

[00:24:37.670] - Clarence Cromwell

And my GitHub repo is on here as well, because I have the original versions of these templates and some templates that I think are not shared with The Good Docs project yet. So I will hand it back over to you, Elizabeth, to see if we have any questions. 

[00:24:58.780] - Liz Fraley

Now it's time to type in those questions if you haven't already, and while you do, here's a look at what's coming up. The TPC Affinity Groups are monthly driven member discussion groups where attendees present their specific challenges to a group of their peers in a confidential, supportive environment.

[00:25:15.330] - Liz Fraley

The affinity groups are a collaborative environment where everyone lends their experience to each other. They can get feedback and advice about topics on their mind in real-time from others who've been in their shoes. It's been amazing to participate in and a lot of fun, too. We have three going on right now. One is everything Techcomm, DITA,  Topic-based authoring, the specifics of cross-references or graphics. The other two are product-focused on Windchill for IT and Arbortext users.

[00:25:42.360] - Liz Fraley

These sessions are not free. They're a way to guarantee commitment between the participants. You can sign up at the TC Dojo Web site at tcdojo dot org. We know sometimes magic is just having the time to collaborate with someone who's been where you are.

[00:25:58.370] - Liz Fraley

What about non-REST APIs? Good question. 

[00:26:03.710] - Clarence Cromwell

Good question. These templates assume an HTTP passed API, I think, for a non HTTP API, I don't have a template for that. And you could certainly you'd be welcome to come in and work on one at The Good Docs project. But I got nothing for you today. 

[00:26:34.200] - Liz Fraley

All right. I've read my share of API docs, but in the long that's the long past now, all right, here we go.

[00:26:45.690] - Liz Fraley

Just a comment, I'm a novice and want to facilitate moving API docs into our program. Thanks for doing that. Awesome! See, people love it. Here's one. Does your reference template assume all content is auto-generated? If not, how do you blend generated and writer written content into the same doc? Great question

[00:27:08.820] - Clarence Cromwell

That's interesting. Oh, here's one thing I didn't explain. We call these templates, but they are... You do not have to open them up and start writing inside that document or fill them in like a form. They are more like a checklist of what should be in the document. So I kind of open up my template over here and I open up a new document over here and start writing my content. You can paste that checklist into your document and kind of delete it as you go. So it's not a strictly template like template, you know, like a form. So it's... so, assuming, does it assume that everything is auto-generated? I think in that sense, it would work either way with auto-generated content or content that was author generated, because the template prompts you to check that the right things are in there. I don't know how you would merge. It's a good question, I don't know how you would merge generated content with separate content written by an author.

[00:28:27.730] - Clarence Cromwell

I know that, for example, if I were working with or at least not in the same build, I think frequently Swagger docs are sort of alongside HTML generated by something else. But I know, so if you're working on Swagger docs and you want to add something, you want to add a description, you just go to the YAML config file, and you have to add the description in there, and I might not have said this, but, in my experience, if descriptions are missing, I'm never able to add them, because if someone needs to explain what an attribute does and it's not there, I don't know what it does. So what I do is I remind the engineers to write that in the...Which is perfect because the YAML file is in their repo and they sort of maintain it. So I point out that they need to add that. And I also try to get them to give me access to the repo and make me an approver on the merge request.

[00:29:34.170] - Clarence Cromwell

And then I can take a look and make the copy edit, or maybe suggest a good sort of format or what would you call it? Like a structure for descriptions. You know, there's kind of a pattern where you start with a verb when you describe what the endpoint does, like returns, blah, blah, blah, or something like that. And you can help a little bit by sort of making all of the descriptions consistent and copy editing them. But essentially you want the engineers to write those in the YAML file for automated content. 

[00:30:14.190] - Liz Fraley

For sure, I remember back in the day at a Juniper, one of the writers had been invited by the engineering team to participate and add comments or add actual content into, like, log messages and API docs prep files. And getting that sort of status and acceptance from the engineering team is a big deal. It can be really useful. And I see we have another comment from someone who said blending two sources very carefully, it adds a level of complexity for sure. And, yeah, it does for sure. 

[00:30:54.620] - Liz Fraley

All right, here's one speaking of request response examples. Should we provide a successful as well as an error example every time? If so, the code samples turn lengthy. True, but always useful. 

[00:31:10.340] - Clarence Cromwell

Yeah, and I think in the reference that's a good idea to know what, at least what HTTP error code you'll get back if it's not successful. 

[00:31:23.940] - Liz Fraley

Yeah, always useful. All right, let's see, and the last one is sometimes tasks need contextual information, for example, details of what the API is in order to understand how to use it. So separation isn't always the right answer, although I do agree in separation of tasks and concept and reference topics.

[00:31:45.570] - Clarence Cromwell

Yeah, fair enough. I think that was... That kind of defines what the dividing line is if you can't do the task without getting that little bit of context. I think substantially the comments that you're talking about after you say do this and show the example, the comments are kind of some conceptual or context information where you say, well, you know, it's only going to work this way. But yeah, but not the full overview where you say, you know, it all started a long time ago because people don't want that much. People don't want that much information when they're doing the steps.

[00:32:29.810] - Liz Fraley

Even though sometimes the engineers want to share that with them, definitely we do. All right, awesome. That was great, great pres, thanks so much. Thank you, Clarence. And I want to check out all the links. That's fabulous. You know, and I think it's cool that you invited people to help work on this repo, it gives you a level of experience that can help you anyway, no matter what, right?

[00:32:59.030] - Clarence Cromwell

It's been great to work on these because what happens is you end up spending a lot of time about how this should look. And that's kind of... Actually took a while to go from zero to where they are now and talking to a lot of people about what the model should look like. There are different, there are definitely a lot of different ways you could organize these. And most of the benefits of this have been in arguing with people about what documentation really looks like and what templates are supposed to do.

[00:33:32.500] - Clarence Cromwell

But actually has a lot of benefits. Democracy is messy and not the best way to do information architecture, but in the long run, you end up learning quite a lot. 

[00:33:45.320] - Liz Fraley

Yeah, here we go. Yes, well worth it. Thank you, Clarence. 

[00:33:49.890] - Clarence Cromwell

Thank you. 

[00:33:52.570] - Liz Fraley

Awesome. Thanks for coming to the TC Dojo by Single-Sourcing Solutions where it's all about you. Subscribe to our mailing list at join dot tcdojo dot org. You'll get a link to this session, as well as announcements for future sessions and a convenient link to the survey. Every month we look at the survey results so we can go out and find experts willing to share their expertise.

[00:34:15.050] - Liz Fraley

Why should we tell you what to learn? You should tell us. Vote now at survey dot tcdojo dot org. As always, the TC Dojo is our pleasure to host. If you need more personal help and want to speak to one of our TC Dojo Experts-in-Residence, just go to ask dot tcdojo dot org where you can get your questions answered and be on your way. Thanks again and see you next time.