 And we have our next speaker, MedidLiv. So we'll be talking about writing good developer docs. So Medid, it's over to you now. Excellent. Well, thank you very much for having me. So my name is Meredid, and I am here to talk about writing good developer documentation. And so I'm going to talk about why documentation is important. I'm going to talk about some of the roles it fulfills that might not be the sort of jobs you think about as your documentation. And I'm going to talk about how our users can help us build it. But to begin with, it would be reasonable to ask why we care about our documentation at all. Well, I care because I'm one of the original creators of Anvil, which is a framework for building web applications quickly, simply, and entirely in Python. So that's Python running in the web browser, Python running on the server, even a Python user interface toolkit. And we have a company that makes developer tools. So an online editor for building applications using this framework with a drag and drop designer and online code editing. And we have an integrated hosting environment, so you don't need to know about DevOps or HTML or JavaScript. You can build and deploy an interactive web application, even if all you know is Python. So obviously, I am pretty keen on developers having a good and productive time with the project I've built. And so should you be. Because whether we are building a web framework or an API for a commercial tool or an open source project we're going to stick up on GitHub and PyPI, we are putting in this effort because we want it to get used. We want developers to find our project, to discover that it exists. We want them to decide that it's useful to them, that it solves a problem they actually have. And we want them to be able to learn how to use it and solve the inevitable problems they'll encounter along the way. Now, traditionally, we think about documentation in terms of these latter tips. But actually, your documentation is important to this entire journey because your docs are so much more than just a learning tool. For starters, your docs are content marketing. If the problem you are solving is real, then somewhere out there is a developer who is opening up the magic search box and typing, how do I do that thing your project does? And your documentation is literally the answer to that question. And so you should be able to find it. Once they found your project, the developer's next task is to decide that it's useful to them, that it actually solves a problem they have, which means understanding what it is. And it's not necessarily obvious what your project is, what it can do, what is its sweet spot, what are its limitations? And of course, the best way to answer these questions is to look at the documentation. The documentation defines your product. Think about it from the perspective of somebody brand new to your project, looking at your table of contents. Is it a good summary of what your project actually does? Or is it a couple of examples of the common case and then a whole bunch of weird edge cases that aren't representative? The difference matters. This is the table of contents of the AML documentation. I actually think it's pretty good. It goes editor, user interfaces, client code, server code, storing data, deployments. I mean, that's not a bad summary of what Anvil the framework is about. And of course, I bring this up because we got it catastrophically wrong first time around because the first version of the AML documentation was structured to match our source code. And as it happens, the AML source code in the AML source code, things like data storage and user authentication and sending or receiving emails and integrating with Google and Facebook and Stripe and so on, they're all the same sort of plugin type object. So they live next to each other in a directory in the source code, which means they were living next to each other in a section off to the side of the documentation, which was no use at all to new users because for somebody approaching a framework for the first time, the question, does this thing store data is so much more important than which third party services it integrates with? So lesson learned, we completely rebuilt the documentation so that the table of contents would be an accurate summary of what AML is about. Okay, so your developer has found your project, discovered you exist. They've decided that it's useful, that solves a problem they have and now it's time to buckle down and learn how to use it to solve their inevitable problems. Now, this at the point, this is the point of course, where your documentation is going to get a real work out. Especially because for developer tools, your documentation is a bit more important because most software is built sort of like a car. Your users in the driving seat, they're looking at the dashboard and the manual is forgotten in a glove box somewhere. But for developer tools, if somebody is using your API, the developer is looking at their code as your documentation and that is it. So for developer tools, your docs are your user interface. They are what your users are looking at all day. And so if you have the skills or the resources, it's probably worth making them look dice if you can. This is the index page of the Trilio documentation. So Trilio is an API for driving telephony systems, so sending and receiving text messages, making phone calls, et cetera. And you can see this is almost like a second homepage because they know that's what their users are going to be spending most of their time looking at. Okay, so we've talked about some of the roles of our documentation. We have talked about why it's important. Let's think about writing some. But of course, documentation isn't some sort of homogenous thing. A tutorial is not the same thing as a reference guide. So we should be thinking about what we're writing. Now, we don't have to do this from scratch. A very clever man by the name of Daniele Prachida has come up with a framework for categorizing documentation. He puts it into four groups. So he divides documentation into your tutorials. So those are the step-by-step guides for learning your way around a project. The explanations, the discursive discussions of how and why it works the way it does. The how-to guides, the step-by-step walkthroughs of a specific real-world task, and the reference documentation, the dry but comprehensive description of everything it does. But actually, Daniele 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 explanations you use when you are studying a project for the first time versus the how-to guides and reference you use when you're actually trying to get something done. And then you've got these step-by-step tutorials and how-to guides versus the more theoretical explanations and reference. So this is a very useful framework and it's interesting to think with. You can learn more at Diotaxis.fr. But I am inherently suspicious of anything that fits too neatly into a two-by-two grid. And in this case, I think the biggest problem is down here in the reference documentation because this framework tries to push too many dissimilar things into that category. Let's look at an example by way of explanation. So the framework says that reference guides are technical descriptions of the machinery and how to operate. This is clearly a good thing. We want these. But this framework also says that reference guides describe the software itself, the APIs, the classes, the functions and so on and how to use them. Well, we want this as well, clearly. But can one piece of documentation really fulfill both of these goals? I don't think so. We're gonna call this stuff reference documentation and this stuff API documentation and they are not the same thing. Here's the example I promised. Let's imagine we are writing unit testing library. So like most unit testing libraries, it has some concept of fixtures, some setup code that runs to prepare the environment and then the test runs and then you run some teardown code to clean everything up afterwards. Now, if we are going to describe the machinery and how to operate it, we need to describe this sequence set up test teardown. We need to tell the story of how these components work together. It's a pretty dry story, but it is a story A then B then C. By contrast, API documentation describes code objects, classes, functions, commands. Everything you write in API documentation is about a class or a function or a command. And if that's all you have, there's not a lot of room for storytelling. So if we were documenting this unit testing library and all we had was API documentation, where would we describe this setup test teardown sequence? Would we put it in the documentation for the setup function, for the test decorator, for the teardown decorator? Would we try and copy and paste it into all three places? There is just no good place in API documentation to convey this important information. And if you try to build your documentation with only API documentation, you will end up suffering from what I call Java doc disease. Now, this is slightly unfair because Java doc is awesome. It was released in 1995. It is the badass great grandmother of every modern API documentation system. It really did shape the world that followed because it let you write documentation like this. So here's a bit of Java doc. I've written a function definition down here. And then above it, I've written a block comment where I've written some text and then I've written a little machine readable description of the arguments that this function takes and its return values and so on. And a program called Java doc will crawl over my code, parsing these comments and the function definitions and generating clean readable, easy to navigate consistent API documentation. It's really, really very good. It makes it so much easier to write documentation because you just have to comment your code. I mean, it's slightly structured but you're just commenting your code. It makes it easy to keep your documentation up to date because the docs are right there next to your code and you can update them in the same commit. And for these reasons, for a long time, the average Java library had much, much better documentation than almost anything else. It was a raging success, but the problem with this success is that it crowded out other forms of documentation. Even today, if you look at the average Java library, there's a good chance that most or even all that its documentation is going to be Java doc, which is to say it's all API documentation and you end up with something like this. So this is the Java doc for a library that parses command line arguments. It's actually, it's good API documentation. It's got an index of all 15 classes that are in this package. You can click through to any of them and you can see what methods they have, what parameter types they take, what they return, how to call them, but how do these classes work together? Which of them calls which others? I don't know. There's no space in this API documentation to express that information. In fact, this is a pretty well-designed library and there is one entry point class that you can instantiate and it does pretty much everything you need to parse command line arguments. It's that one. Did you spot it? Of course you didn't. This is API documentation. There is nowhere to express this important information. So when you are structuring your documentation you've got to think of API documentation and reference docs as two separate things, two separate top-level categories. Reference documentation describes systems, machinery and how to operate it. API docs describes code objects, A module, A class, A function, A command. Reference docs tell a story, set up, test, tear down. It's a pretty dry story but it's a story. API documentation stands alone. You should be able to consult the API documentation for a function and find out quickly and concisely what it does, how to call it. The reference docs should be structured logically according to how your system works. API documentation should be structured to match your source code because it should be generated automatically. So okay, we've added a category, we now have five top-level categories of our documentation but of course these are not separate things. Nobody is going to read your reference documentation 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 and that journey might touch a few different pieces of documentation. Here's an example. So we have a developer. They are wondering what they should use to solve this problem. It's sitting around in the back of their mind when they wander across a blog post saying, hey, this project over here is pretty cool. So they go check it out, they ask, how do I use it for my task? Well, ideally, there should be a how-to guide to explain that. So okay, they're convinced it's going to solve their problem. Now it's time to dig in, to start writing some code. Maybe start adapting the how-to guide to that specific situation. Maybe write some new code and they're going to want to know what arguments this function takes. And this is clearly a job for the API documentation. So you can see they've been steadily zooming in to sort of fire and finer levels of detail here. But that's not the only way to do it. Here's another journey. A developer wonders, how do I do such and such? So they do what we all do and they plug it into Google and they land on a how-to guide. Remember, your docs are content marketing. So okay, they're looking around this and they're wondering, how does that work? Well, they want a bit of slightly more detail than just a prescriptive guide. Reference docs, machinery, how to operate it. Okay, they read a page or two of this, they're convinced. Time to learn this thing properly. Let's do a tutorial. This is again, this is a perfectly legitimate journey. But this time they're zooming out as much as they're zooming in. Every user is going to be on their own journey through your documentation. And it's your job to make it easy for them to find what they need next. And that might not be the same type of documentation they've just been looking at. Now, the easiest way to do this is hyperlinks. Link from everywhere to everywhere else that's relevant. If you're writing a how-to guide, you're going to be narrow and task focused. But every topic you mention, you can link to the reference documentation so they can discover more about that piece of machinery. But equally, when you're writing your reference documentation, whenever you're covering an appropriate topic, link to the tutorial on that topic if you have one. That way, your user can zoom out from a specific piece of machinery to, okay, how does this system work at a high level? And of course, your API documentation and reference documentation should be heavily, heavily linked with each other. They're not the same thing, but they work closely together because if somebody is looking at a piece of machinery, they should be able, and how to operate it, they should be able to click through to find what arguments this function takes. And likewise, if they are looking at the API docs for a class, they should be able to very quickly click through to see what story that class is part of. So hyperlinks everywhere, but links aren't the only way to do this. You can also just put them next to each other. So this is another piece of the table of contents of the Anvil manual, and this is the section that deals with user management. So Anvil has a built-in user sign-up on authentication system. And the first two pages here are actually tutorials. We call them quick starts, they are tutorials. They take you on a guide through the system. And the rest of these pages are reference documentation. Now, we have to be very clear, every page needs to know what sort of documentation it is, because if there's one page that's trying to be tutorial and reference at the same time, it's going to be a disaster. You're going to be neither comprehensive enough to be good reference documentation, nor step-by-step enough to be a good tutorial. But you can put those two next to each other to make it really easy for users to zoom in and zoom out whenever they need to. Okay, so we have our categories of documentation. We have some idea of how they're going to work together. But now, of course, we have an infinite to-do list because there is so much to write in each of these categories. What's most important? What should I focus on next? Well, the best way to answer this question is, of course, to talk to your users. Because if you are talking to your users, you will hear where they need more help. You will hear what is not being properly communicated in your documentation. Now, the best, most high-fidelity way to do this is to do it in person. So this is by colleague Bridget at PyCon. Last time we could actually have conferences in person, do you remember those days? But even if when we do have conferences in person, of course, you get a really high-quality conversations, but that doesn't scale. So you should probably also have an online platform. We use this course, the free forum software. Honestly, I can't recommend it enough. It's got great functionality. It is easy to set up. It is open source and it's actually really simple to set it up and host it on your own servers. Or if you're not up for hosting another piece of software, you can go with Stack Overflow, also a good platform. Or of course, you could set up a Slack or a Discord instance. No, please don't use Slack. Your documentation is stuck behind a what signup wall and the conversations are ephemeral. It scrolls away in a day. And that's a problem because every question is a bug report against your documentation. But if they are answered somewhere public and searchable, every answer is a patch. And those patches naturally gravitate to the polls in your documentation. So if it is publicly searchable, I mean, your users can help you prioritize what needs to go upstream, but even before something goes upstream or if a question is too obscure to go upstream, your Q&A section, if it is public and searchable, forms a sixth pillar of your documentation that fills in the holes from the other five. But now I've made an absolute dog's breakfast of Daniela's beautiful diagram. I will never make it as a management consultant and it's probably time for me to wrap up. Remember that your documentation is your user interface. But it is your content marketing. It is the answer to the question, how do I solve this problem that lots of developers have? It is the definition of your product, that anyone who's not already familiar with it, which is to say, nearly everybody. And so for heaven's sake, act like it, especially if this is a commercial project, if you are parched in the desert, dying of thirst for lack of user attention. Remember, this stuff is important way up to the start of your funnel. So know which sort of type of documentation you are writing. Think about your tutorials and your references and your how-tos. Remember that API documentation is not reference documentation and you probably need both. And talk to your users because they will help you fill in the gaps. I've even read a little up, thank you very much. Yeah, so I've heard many things. That was really a wonderful talk. I think we don't have any questions but so one of the questions I have from my end in the day. So what kind of a tip for solutions if you want to give someone as a beginner, who wants to contribute to open source documentation? So if you want to say that again, please. So let's say if you want to give some suggestions or tips who wants to start contributing to open source documentation. So if you want to start contributing to open source documentation. So if you're starting with an existing project then I want to just flip back to the side that says talk to your users because if it's an open source project somewhere out there there's going to be the evidence of where users are having trouble. So go in and troubleshoot. Find something that people keep opening GitHub issues about or people keep asking on Stack Overflow or on your Q&A forum or in Slack or whatever and go hey I'm going to write a how-to guide to tell you how to do exactly that. So use that prioritization system and you will go and fill a need and so your pull request when you turn up with one is much more likely to be accepted. So that would be like if you wanted to start contributing to open source documentation, listen to the users heck listen to yourself, you are one of them and document the thing that would really solve a lot of pain you're seeing out there in the community. That's a great answer.