What You Need to Know About Your Documentation - Daniele Procida

Hello everybody. It's very nice to be part of this first remote DjangoCon Europe. A huge amount of work has gone into this event, so many thanks to the organizers for putting it all together. In case you don't already know me, I'm Daniele, Chief Collaboration Officer at Divio. And at Divio we have a web application deployment and cloud management platform. We have hosting clients including, for example, companies like Fidelity International and UBS. UBS I can mention, but sadly I'm not permitted to use their logo here. And if your business is creating web applications, but you find that things like provisioning new S3 storage instance

instances, or migrating a complex application to a different Cloud region can cost you a lot in effort or money, or maybe just too much time spent crying in front of your computer, then maybe DVO can help you. You don't have to be the size of Fidelity or UBS, and you don't even have to be at the tearful stage, and in fact, it's always better to get help before you reach that point. I'd be very happy to talk to you about that. But what I'm here to talk to you about is technical documentation. And the key thing to understanding documentation is this That documentation isn't just one thing, it's four different things.

And we speak of it as if it were one thing, monolithic or even homogeneous But that has the effect of concealing its nature from us. Here are those four things. These four tutorials, how-to guides, reference and explanation are the four types or forms or components of technical documentation. and they represent four different objectives or functions. A complete set of documentation for a product or project needs to contain each of them and it needs to be structured, explicitly structured, according to this scheme.

Each of them requires its own distinct style of writing. Each has its own purpose, each answers to a specific need, each has its own particular task. Each is separate and distinct from the others and needs to be kept so And that's the key to making documentation easier to maintain and to use. What I want to do now is go through each of the four in order in order. Tutorials, how-to guides, reference, and explanation. We'll start with tutorials. Now a tutorial is a lesson. A lesson that takes the reader by the hand through a series of

practical steps to realize a project or complete a meaningful exercise. A lesson is an experience, a pedagogical experience Think about the experience of teaching a child to cook. Perhaps this is an experience you you're already familiar with. What works when you're doing that? What doesn't work? And the question that needs to be understood is how is it that one learns a new skill And the answer to that is the only way one learns a new skill is by doing. And a successful tutorial, therefore, has to find a way to put that principle

into practice. Tutorials are learning oriented. Your task in creating a tutorial is to create a learning experience. One in which the pupil learns by doing things under your direction and to provide or constitute a learning experience, your tutorial must be repeatable, must instill confidence, must result in success every time for every learner. It must be concrete and particular. On the other hand, things like abstraction and generalization, or Explanation, information, and choices, they don't belong here.

In a tutorial, these are kinds of pollution They damaged the learning experience. They're temptations, anti-pedagogical temptations, that are very easy to fall into. So the only preoccupation of your tutorial should be, what will your pupil do in order that they shall learn? And I can tell you quite safely that tutorials are the least well-understood part of documentation, the most difficult part to create. to maintain, to write. And without doubt you'll find that the most they are the most badly executed part of the tutorial, of the documentation that you encounter. So

it really should be pretty clear. A documentation, sorry, a tutorial uh that functions as a lesson is always going to be suboptimal You're responsible for the pupil's success, you're responsible for their learning, you're responsible for providing an experience that instills confidence, and at the same time, you're condemned to be absent And if that sounds a little bit unfair, then I think actually y you're right. Uh for my own part, mate writing and maintaining tutorials occupies alone, just by itself, something like 80% of my time when I'm working on documentation and probably accounts for something like 99%

of the difficulties that I face. Next, how-to guides. A how-to guide takes the reader through the steps required to complete a specific task or solve a specific problem which amounts to the same thing. How-to guides are recipes. Think about the recipe for preparing a dish. What's the function of a recipe? What form does a recipe take? What would you expect to find in a recipe, and what would you consider? out of place. In documentation, how-to guides are task-oriented or problem-oriented So a kitchen recipe is a very good model for a how-to

guide because it has a practical utility. It moves towards a clear objective. It serves not the beginner, but the already competent user. Unlike a tutorial, it has no obligation to the needs of the learner. And it shouldn't be confused with a tutorial because its purpose, its audience, its needs and its style are quite different In a tutorial, the language is imperative. If you want to do this, if you're sorry, if you want to achieve this, do that. It responds to a question, how do I do such and such with a series of actions and only actions without digressions or explanations or attempts to

teach? Next we have reference guides. Reference guides are technical descriptions of the machinery and its functioning. They've got just one purpose, to describe in the most correct and complete manner possible. So think about the form of an article in an encyclopedia, a reference work. What does such an article do? What does it present? What kind of style does reference material adopt? Reference material is information oriented.

It's Technical description has to be complete and correct and whereas tutorials and how-to guides need to answer to the uh have to answer to the needs of the reader, technical reference has other obligations, obligations only to the facts, to to the machinery, not to the person who's using that documentation. So, reference material should be free of distractions from its purpose. It should be austere and uncompromising. It's governed by principles like neutrality and objectivity and factuality. And It should be structured, it should be written according to the structure and the architecture

of the machinery itself. They should share a common architecture. Finally, we have explanation. Explanation is discussion that illuminates and clarifies some particular Topic. Explanation opens up a subject, adopting a wider view of it. Think about a book that's concerned with the art, the science, the history, and the cultural significance of food and cooking and eating. It's not a book of recipes or of technical information or one that teaches skills. It's discussion at another level altogether, explanation. E even the word explanation is a clue.

It's concerned with unfolding, with spreading out. Explanation un covers things that may have been obscured in the folds of the matter and makes them plain So explanation is understanding oriented. It's a discussion that Opens the subject in multiple directions, outwards, deeper towards the past and the future. It offers context and establishes connections. It answers to the needs of the person Who wants to un who wants to know more? It deepens the theoretical understanding of a practical craft Its style is discursive

and it can go where the other parts, tutorials, how to guides and reference are forbidden to trade. It can go into the bigger picture, into history. it can go into things like choices and alternatives and possibilities, and it can ask why and seek reasons and justifications for things and why they are the way they are. So here they are, all four of them: learning-oriented tutorials, task-oriented how-to guides, information-oriented reference, and understanding-oriented explanation. This is clear and and beautiful. It's a structure that technical documentation should have explicitly. And sadly, this is what documentation usually looks like.

It's terribly difficult to keep these four different things apart from each other Because there's an internal gravity, a kind of fatal attraction that's always pulling them together. And the disorder and confusion that result is hardly the fault of the authors of documentation It's very difficult to resist the tension inherent in the structure. A tension that's caused by the way in which the characteristics of the four different kinds of documentation overlap with each other. I'll show you what I mean. Here we are with each component neatly in its own quadrant where it belongs. And if we look more closely, we see

tutorials and how-to guides are similar because they're both concerned with describing practical steps. and how two guides in reference share with each other that they both serve our work. They are what we need when we're actually working. And reference and explanation are similar because they're both concerned with theoretical knowledge. While explanations and tutorials have an affinity because both serve our study of the subject So you can see the overlaps

or the um characteristics that they share with each other and how they do that, and you can see how that pulls them inwards. So naturally we have this total collapse this implosion of the structure. But no, this is what we want. This is what it should look like. When it does look like this You will have documentation that works better, that's easier to write and maintain, that's easier to use and to find your way around in as a reader. And it will do at least a part of the work of documentation for you. It won't write itself but you'll have a much clearer idea of what to write, how to write it and where to write it. And it will serve your users better because for all the different phases and the cycle of their interaction with your product

They're going to find the right kind of documentation that serves the needs of that moment. Let me give you one more example from Aviation. In brief, we have the tutorial, the lesson, the pedagogical experience safely in the hands of the instructor who's going to direct you what to do. Then we have the how -to guides, the recipes for the skilled practitioner here in the case of uh here in this case in the form of a checklist for flight operations. Then we have reference, the information that's required in order for us to be able to do our work. Here it's cartographic information, landing charts. And

we have finally explanation, discussions that deepen the understanding. In this case it's an explanation of what lies behind the behavior of an aerodynamic system. And in each of these cases, what's present and what's absent conforms with the model of documentation that I've been speaking about. And you'll find that this model makes sense in all kinds of documentation contexts, and you'll see the elements there and how they perform their functions. This isn't the only model of documentation, but I do think it's the best one. So That's the theory. What about

the practice of documentation? Well, first thing, this system is used a lot in a wide range of different products, including both open and proprietary software. Here it is in Divio's own developer handbook and you'll notice that some of the names are different, but that doesn't matter. We have get started, our tutorials, background, our explanation. But otherwise we have the four sections just the same way. Here's one of our tutorials for building a Django project on DVO. The tutorial makes a promise. If you follow this tutorial, you will have created and deployed a production-ready Django web application using Docker, complete with Postgres database, S3 Media Storage, and so on. It doesn't tell you what you'll learn. It's not so presumptuous. It just tells you what you're going to do.

And the learning comes out of that doing. The tutorial determines what you will do, the order that you do it in, and it just decides what you don't need to know about right now, and so on. It takes full responsibility for all of that. Next, we have um one of uh here's a list of some of our how-to guides. Each one is an answer to the question, or an answer to a question or a problem, how do I do such and such? And each title, as you can see can be preceded by the words how to, how to manage a project's base image, how to run the local server in live configuration. Practical tasks. And if you look at one in more detail, you'll see it takes you through a series

series of steps to complete a practical task Here's an example of one of our reference guides. It's technical description and nothing else. This is the machine. These are its functions. This is how it's operated. This is what it will do. And finally, some of the explanation articles. They don't teach you anything, they don't tell you what to do, they're not reference guides, they just discuss a topic in uh at another at another level. You don't need to know about say caching and CDN or how we manage environment variables in order to achieve any particular task. But the time is likely to come when your use of the platform will be improved by having a clearer, better and deeper understanding of those topics. It's the bigger picture, the context.

And you're a human being, so maybe you don't strictly need to know why we do a certain thing in a certain way, but knowing it might well provide you with a kind of satisfaction and comfort. that makes you a happier, uh more at ease user of the product, which is what we want Here it is in Django. Again, some of the names can be a little different, but the structure is same. Tutorials, explanation, here called topic guides, reference guides, and how to And in one of my hobby projects, uh the Brachiograph, a Python-driven pen plotter, it's probably the cheapest, simplest Pen Plotter in the World. Get started for the short tutorials how to reference and explanation

So you'll find this structure in many places and uh uh especially in the Python world of course, but elsewhere as well. I'm aware of the adoption of the system in numerous projects, in which it's applied sometimes in a more complete way and sometimes in a less complete way, but Um it's it's there and often it's explicitly mentioned. Here are just a few of them. You'll recognise some of these from uh Our World of Python and Django, like uh BWARE and NumPy, but there's also loop back from IBM and uh and others. And also some private examples. I don't know so much about those. I'd love to know what Bosch or Ericsson are are doing with it. All I know is that somebody there is using the system for their technical documentation.

And I receive almost daily feedback and messages from authors and people involved in projects who use or study the system in one way or another. And we know it works. It's tried and trusted across multiple projects. And it works really well as a tool in the hands of the writer of documentation. Often an author author will know that there's a problem with their documentation, but knowing exactly the nature of that problem is a different matter, so they'll wrestle with queks questions like, How is it possible that our documentation appears to be harder to maintain than our actual code? Or Where is this new material supposed to go? Or what am I doing here? What am I trying to say? And here it works as an analytical or diagnostic tool, shining a clear light

on the problem, allowing you to see what's wrong, which might be that, hmm, this section I see of the tutorial detracts from the learning experience, or This reference material is clearly in the wrong place, or this how-to guide has become bloated with explanation And it's also a synthetic, which is to say a productive instrument. It can guide you while you're at work creating your documentation. What style should I be using here? Where should this material go? What's missing here? What is the purpose of this page? So for the very last time here's the synoptic picture of the system. Here's your map for your documentation

and what you should be doing while you're working on it I'll leave you with a link to some more information about the system at documentation. dvo. com. And if you'd like to know more about documentation or want to talk about it or even would like some advice on how to improve your own, please do talk to me. I'd love to talk to you about it. I'm happy to help people work with their documentation. And at the same time, if you'd like to know more about DVO or how DVO can help you put complex web applications into production without having to shed tears over cloud management or DevOps, you also know where to find me. Thank you very much, and I look forward to seeing everybody again at another conference sometime

when it's safe to meet again.