 We have Merited, who's going to talk about writing better documentation for developers. Merited thinks programming should be more accessible. From discovering that QBasic was the best toy ever to a PhD in building usable programming systems, he wants other programmers to have the same fund that he's having. So these days, he's a founder at Anvil, which makes full stack interactive web apps. Over to you, Merited. All right, thank you very much for being here. Do I have to, oh, there we go. All right. So hello, thank you very much for having me. My name is Merited, and I am here to talk about writing good documentation for developers. So we're going to talk about why this is important, about the various roles that your documentation can play in the lifecycle of your project, and then about writing them, about the types of documentation, about how they can work together, and how our users can help us. But it's reasonable to start by asking why we care in the first place. Well, I care because I'm one of the original creators of Anvil, which is a web framework for building full stack applications entirely in Python. So that's Python in the web browser, Python on the server, even a Python user interface toolkit. And we have a company that makes developer tools. So we have an online editor building applications with this framework, with a drag-and-drop designer, and a code editor, and a built-in database, and also a built-in hosting platform. So you don't need to know about DevOps or HTML or JavaScript. You can build a web application and put it online, even if all you know is Python. So obviously I'm pretty keen on people having a good and productive time with the project I build. And so should you be, because whether we are building commercial APIs or open source frameworks or projects we're just going to stick up on GitHub and PyPI, we're putting this effort in because we want them to get used. We want developers to find our projects, to discover that it even exists. We want them to decide that it's useful, that it solves a problem they actually have, and we want them to be able to learn how to use it and to solve the inevitable problems they're going to have along the way. Now, traditionally we think of documentation in terms of these latter two, but actually documentation is important to this entire process because your docs are so much more than just a learning tool. For one thing, your documentation is content marketing. I assume that the problem that your project solves is something that real people are experiencing out there in the world, but if so, then right now out there, somebody is opening up the magic text box and typing, how do I do that thing that your project does? And your documentation is literally the answer to this question. And so they should be able to find it. Of course, once they found your project, the developer's next task is to decide whether it's any use to them, which means they need to work out what it is. What can it do? What's it good at? What is its sweet spot? And to do this, they are most likely going to consult the documentation so your docs define what your project even is. Think about the experience of a new developer or potential developer coming across your documentation and scanning the table of content. Do they see a structure that reflects, yes, that is what this project is about? Or do they see one code example of the common case, one great big assumption that the common case, everything else is obvious, and then three pages of random edge cases? The difference matters. This, for example, is the table of contents of the Anvil manual. And I actually think this is pretty good. You've got editor, user interfaces, client code, server code, storing data, deployments. That's not about summary of what Anvil is about. And of course, I bring this up because we got this catastrophically wrong first time round because the first version of the Anvil documentation was structured like our source code. And that seemed like a good idea at the time. But as it happens in our source space, things like data storage and user authentication and sending receiving emails and like integration with Google and Facebook and so on, each of those is the same sort of plugin type object, which means that they live together in a folder in our source space, which means that they were living together off in a side folder of our documentation, which was incredibly unhelpful for new users. Because of course, for a new user evaluating a framework, the question, does this thing store data is much, much more important than which third party services does this thing integrate with. So lesson learned, we restructured our documentation deliberately so that the table of contents would be an accurate summary of what the project actually is. So your developer has found your project. They've decided that it's useful. And they want to sit down to learn how to use it and solve problems. Now here, obviously your documentation is going to get a real workout. And this is especially true of projects for developers. Because if you think about most software, most software is built a little bit like a car. The user spends most of their time looking out of the window or at the dashboard. And the manual is basically forgotten off in the glove box somewhere. But if a developer is using a developer tool, then they will spend their time staring at their code and your documentation. And that is it. So your documentation is your user interface. And you should treat it with that kind of priority. In particular, if you have the skills or resources, it's probably worth making it look nice. So this is the documentation index for Twilio, which is an API for driving telephony systems that's making calls and SMSes and so on. And you can see their docs index is it's almost like a second home page because they want it to be pretty to look at, easy to navigate and to define their product for someone clicking around the documentation. So we talked a little bit about why our documentation is important and the way that it's important in some ways that we might not think about. So it's time to sit down and write some. But of course, we don't talk about three ounces of documentation. Documentation comes in many different types. Your tutorials are not the same things as your reference docs. So we actually don't have to reinvent the wheel here because a very clever man by the name of Daniela Parchida has already come up with a framework for dividing your documentation. He reckons into four different types. So he divides your documentation into tutorials. So those are the step-by-step guides to walk you through a project for the first time. The explanations. So these are the discursive discussions of how and why your project works as it does. And then you've got the how-to guides, the step-by-step guides to accomplishing specific real-world tasks. And then you've got the reference documentation, the dry but comprehensive description of everything your project does. And I honestly think Daniela would make a pretty good management consultant because he's even got a two-by-two matrix going on here. You've got the tutorials and the explanations which are used when you're studying a new project versus the how-to guides and references you use in the process of trying to get a real-world task done. And then you've got the practical tutorials and how-to guides with step-by-step versus the more theoretical explanations and references. And this is all very neat. It's quite insightful. You can check it out at dietaxis.fr. But I am inherently suspicious of anything that fits too neatly into a two-by-two matrix. And this is no exception. In this case, I think that the biggest problem lies over here in the reference documentation. If we click through and read the descriptions, Daniela describes reference documentation as technical descriptions of the machinery and how to operate it. Well, that's clearly a good thing. We definitely want that. But he also says reference guides describe the software itself, APIs, classes, functions and so on and how to use them. Now, that too is clearly a thing we want, but can one piece of documentation really satisfy both of those goals? I don't think so. I'm going to call this stuff reference documentation and this stuff API documentation and they are not the same thing. To illustrate, let's imagine that we have built a unit testing framework. So here's its API over here. And like most unit testing frameworks, it has this idea of a fixture. So you've got some set up code that runs before the test and then you run the test and then you run some cleanup code to tear everything down afterwards. Now, if you want to describe the machinery and how to operate it, then you're going to have to describe this sequence. So your reference docs need to tell a story that may involve multiple components. Set up, test, tear down. It's a pretty dry story, but it's a story. By contrast, your API documentation describes code objects, a function, a class, a command. And if you're describing one code object, there's not really much room to tell a story. Let's go back to our unit testing example. If all we had were API documentation and we wanted to describe this set up, test, tear down sequence, where would we describe that? Would we describe it in the API documentation for the set up decorator, for the test decorator, for the tear down decorator? Would we try and copy and paste it into all three places? There's just no good place to put this information in API documentation. And so if you don't realize that API documentation and reference docs aren't quite the same thing, then you're vulnerable to something I call Java doc disease. Now, naming a disease after Java doc is kind of unfair because Java doc is awesome. It is the badass great-grandma of every modern API documentation tool. It was released in 1997, and it works like this. So, here I've defined a function in Java, and then before it, I've put a comment. And this is a slightly structured comment. It's got the description of the function, and then it describes the argument and the return value. And a program called Java doc will walk over my source code, parsing these comments and the function definitions that follow them and spitting out clean, consistent, cross-referenced API documentation in HTML. And this was a huge advance. It makes it so much easier to write documentation because you just comment your code. It makes it so much easier to keep your documentation up to date because the docs are right there. You can change them in the same commit as you've changed the code they're talking about. And because of this excellent tool support for a very long time, your average library written in Java was much, much better documented than almost anything else. But there's a problem because Java doc became a sort of victim of its own success. If you look at a Java library today, still very good chance it's got documentation, which is step one, but it is really quite likely that all or nearly all of the documentation is Java doc, which is to say it's all API documentation. And so you get things that look like this. Now, this, I've deliberately zoomed it out and blurred it, is the documentation for a command line parsing library. It's actually really good API documentation. It lists the dozen or so classes in this package. You can click through to any of them and find out what their functions are, their attributes and so on. But does it tell me how to use it? No. Actually, this is a really well-designed library. It's got a single entry point class, which you can instantiate and it will do pretty much everything you need to do in terms of command line parsing. It is that one. Did you spot it? Of course you didn't. This is API documentation. There was no place to express this important piece of information. So if you're writing your documentation, I'd urge you to think about API docs and reference docs as two different top level categories. Your reference documentation should describe systems, the machinery and how to operate it, and that machinery can be composed of several different components working together. API docs describe code objects, a function, a class, a command. Reference docs should tell a story, set up test to tear down. API docs should stand alone because you should be able to easily find and consult the API documentation for a specific code object. Reference docs should be structured logically to match what your project does. API docs should be structured like your code because they should be generated automatically. So we've now got not four but five top level categories of documentation and it's worth thinking about how they should work together because let's face it, just about nobody is going to read your reference documentation in a straight line from beginning to end. Heck, very few people are going to read all of your tutorials from beginning to end. Your user is on a journey that will probably take them through several different types of documentation on the way. Let's look at an example. So a developer has a problem sitting in the back of their head and they're wondering what they should use for it. And so they stumble across a blog post saying, hey, this project really is the bee's knees. And so they go, okay, well, how should I use it for my specific task? That's clearly a job for your how-to guides. Okay, they're convinced. They've started working from this how-to guide. They're now starting to customize the solution. They want to know what arguments a function takes. Well, that is clearly a job for your API documentation. So you can see they've sort of gradually zoomed in to more concrete, more specific, and smaller descriptions, a finer grained descriptions of what your project is. But here's another trajectory. A developer asks, how do I do such and such? And they do what everybody does, which is plug it into Google and they land on one of your how-to guides. Remember, documentation is content marketing. So they read it. This seems to be relevant to them, but how the heck does that step work? Well, clearly that's a job for your reference documentation. Explains the machinery. Okay, I'm convinced. I've read a few pages of your reference documentation. I need to learn how to use this framework properly. Well, time for a tutorial. And now this user is zooming out as much as they're zooming in. And you're going to have as many different paths through your documentation as you have users. So you want to support flitting between types of documentation. The easiest way to do this is, of course, hyperlinks. Just link from any sort of documentation to any other sort of documentation that described the same topic. So, for example, in a how-to guide, you should link to the reference documentation for every piece of machinery you talk about. Your reference documentation should link to tutorials about the topic it's covering so that the user can zoom out and get a broader overview if they want to. And of course, reference docs and API docs should be linked together really extensively because you will want to jump back and forth all the time between this is the machinery and how I work it, and these are the arguments that this function takes. But hyperlinks aren't the only way to do it. You can also just put these documentation next to each other. This is another piece of the table of contents of the Anvil Manual. This part talks about the built-in user authentication system. And actually, these first two pages are tutorials. We call them quick start, but they are just tutorials. And they are followed by pages of reference documentation. Now, notably, each of these pages knows what it is. Nothing is trying to be a tutorial and a reference doc at the same time because that way lies madness. But by putting them next to each other, we make it really easy for developers to zoom in and zoom out. So, okay, we have a concept of what types of documentation we have. We have a concept of how to make them work together, but what should I work on next? I mean, prioritization is one of the big problems of life, but in this case, there is one tactic I can very, very heartily recommend, and that is to talk to your users. Because if you are talking to the developers using your project, you will hear what they are not understanding. And if they're not understanding something, you probably haven't explained it well enough. Now, obviously, the best way to do this is in-person. So this is my colleague Bridget in Cleveland. Last time we could have conferences in person. I can't wait to be back. But even when in-person conferences resume, this is somewhat retail and doesn't scale. So we also have an online forum. We use the discourse and we can heartily recommend it. It is free, it's open source, it's remarkably easy to set up and host yourself. But if you don't want that faff, you can also use Stack Overflow. Or of course, you could set up a Slack or a Discord space. No, do not use Slack, please. If your question and answer forum is a Slack channel, then the questions are ephemeral, they'll disappear. And in any case, the questions and the answers are all locked up behind this registration form. And that's a problem. Because questions are bug reports in your documentation. And the answers you give to those questions are patches. If you answer a question somewhere public and searchable, then that answer can help anybody else who's stuck on the same question. And even better, because this process is driven by the questions your users are asking, these patches naturally gravitate to the holes in your documentation. And if you use a system with voting, like discourse with its likes or Stack Overflow with its upvotes, then your users can even help tell you which of these patches are most urgent and need to go upstream into your main documentation. Now, of course, not everything needs to go upstream immediately, some questions are too tangential or too obscure for your mainline documentation. And that's okay, because if your Q&A is somewhere public and searchable, then it effectively forms another pillar of your documentation. And so your documentation becomes sort of self-healing and the long tail takes care of itself. But now I've made an absolute dog's breakfast of Damiele's beautiful diagram. I will never make it as a management consultant and I think it might be time to wrap it up. So let me finish by reminding you that your documentation is your user interface. It's what your users will be staring at all day. Your docs are marketing. If you're solving a real problem, people are looking for the solution to that problem and your docs are the answer to their question. Your docs define your product to anybody who hasn't heard of it yet, which is to say, nearly everybody. So for heaven's sake, act like it. This goes especially for commercial projects. If you are out there, parched, dying in the desert, wanting attention from users, remember that your documentation is important much, much earlier in the user acquisition process than you probably think it is. So when you're writing documentation, think about what type of documentation you're writing. Remember that API docs are not reference docs and you do probably need both. And talk to your users because they will help you fix the holes. Thank you very much. Thanks for that amazing talk, Meredith. We have time for questions, so let's do it. Okay, let's do it. Okay. Okay. Is auto-generated API docs from DocSprings function signatures ever sufficient? Or do API docs always require manual editing or polishing? I think the answer is yes to both of those questions, but the way you should polish your API docs is to write good DocSprings. Yes, absolutely, you need to put effort in there. And absolutely you should be putting, you should be annotating it with things like cross references into your reference docs and things like that. Sorry, I don't buy the dichotomy, yes to both. All right, thank you. Next question. What do you think of DocTests? Oh, is this the thing where your documentation actually contains embedded code and your CI system verifies that those examples actually work? Is that what you're asking about? There's no explanation to the question. I can't do the chat from here. But there is no explanation to the question as such, but I believe we can work with this right now. Okay, right, so, I mean, I'm in favor, I acknowledge that we don't do it ourselves for the Anvil documentation. I've seen systems that do it and they do tend, it does kind of cramp your writing style because it does kind of mean that every code sample needs to be complete because it needs to be executable, which means that it can be difficult to sketch things rather than writing one big working program and then walking someone through it, which is a valid technique, but sometimes you want to go step by step and look at individual lines and sometimes the need for something executable everywhere can get in your way. So I know that's why we don't do it, but I don't have the sufficiently informed opinion on the Prax channel. Okay, thank you. Onwards to our next question. What is your recommendation to store project-specific documentations, for example, guidelines, explanations, et cetera? So are you talking about like storing technique? I mean, so all documentation is project-specific. And again, I'm not quite sure what you're going for. You're talking about things like contributed documentation because that's, I mean, guidelines sounds like contributed guidelines, which is, yes, I mean, that's an important part. If you're hosting something like an open source project, then that's an important part of your documentation. I mean, most GitHub projects I've seen have a sort of contributing section. And I mean, you store it wherever your users are. This entire talk was kind of agnostic to how you present your documentation. Now, obviously, we are a developer platform. So we could afford to put a lot of engineering effort into a custom documentation platform. So that's what we do. But none of this really prevents you from using any of the standard off-the-shelf tools and just wherever you are in your off-the-shelf tools, whether you are writing Markdown in a GitHub repository or Syncs, or whether you're running something, running your own, like we are, just have somewhere to put the documentation that you're always going to need, if you're not just writing API documentation, if you're writing the other sorts of documentation, you're always going to need something that approximates a piece of hypertext and linked websites with tables and contents and so on. And your contribution in instructions or behavioral guidelines should be somewhere in there as well. Great, thank you. So we have time for another couple of questions. So let's look at them. If you encounter a project with non-accessible documentation for newbies, would you recommend putting up an issue or even write a Hello World example as a whole request? So this sort of depends on what sort of documentation. And this question is, I feel like this is going to be a very political answer because what counts as non-accessible documentation and what the existing authors are targeting are live questions. So what you're asking me is kind of a social interaction question about whether you talk to the maintainers about, hey, this stuff isn't accessible. I'm interested in contributing some getting started stuff. Where within your documentation scheme would it go? Do you have opinions? I mean, that's probably what I would do, especially because as an open source maintainer myself, when someone comes to me and asks that, I bite their hand off. But I don't think there's anything inherently wrong with submitting a pull request. Just acknowledge that if the documentation doesn't already have anything sort of tutorial shaped, then if you submit a pull request that has a bunch of opinions about where the tutorials should go and how they should fit with your documentation, it's a little bit like turning up with a massive pull request that changes the structure of the code or has opinions about how the code is laid out. And if you haven't talked to the maintainers first, you may then have a socially awkward conversation about how actually, thank you very much for this work, but I really wish you would have talked to me first because just a few changes early in the process would have made it so much easier to merge. So yeah, that's a social question with a social answer. Fair enough. Obviously, like the bottom line here is people who want to contribute more accessible documentation to projects, have all the confetti, please do it. Great. Great, thank you very much for that talk and taking on all those questions. I think people would love to hang out with you in breakout room, Optiva. So... Excellent, well, in which case, I will see you all there. Thank you very much for having me. Thank you.