Cloud Native Computing Foundation KubeCon + CloudNativeCon Europe 2021, 14 May 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Writing for Developers: Take your Project Docs to the Next Level - Celeste Horgan, CNCF

Description

Don’t miss out! Join us at our upcoming event: KubeCon + CloudNativeCon North America 2021 in Los Angeles, CA from October 12-15. Learn more at https://kubecon.io The conference features presentations from developers and end users of Kubernetes, Prometheus, Envoy, and all of the other CNCF-hosted projects.

Writing for Developers: Take your Project Docs to the Next Level - Celeste Horgan, CNCF

As maintainers know, when choosing an open source project to use in production, great documentation and community support are key. Yet they often struggle with creating and maintaining documentation because of lack of time and skill. This talk, delivered by one of CNCF’s full-time technical writers, will teach you how to approach writing for developers. We’ll go over deciding what to write, thinking about documentation from a user’s perspective, and what makes great writing. We’ll walk through improving an existing page of documentation on an actual CNCF project(*), as well as how to draft new feature documentation from scratch. This talk is aimed at developers who would like to write better, and folks considering a career switch into technical writing. (*) Project TBD.

A

Hello, everyone, my name, is celeste horgan, I'm a senior technical writer at the cncf, uh and this is writing for developers, take your project docs to the next level.

A

um So, let's start with a fun fact about 50 of responses to the query: how to choose a development framework on stack overflow mention documentation in the response: um full disclosure. This is a pretty rough estimate done by me. I uh spent some time googling how to choose a dev framework, how to choose a devops tech stack et cetera and combed through the responses by hand, um but the vast majority of them do mention um speed of learning availability of documentation um and how many responses something receives on stack overflow.

A

um So this is a bit of a call to arms. For you, this talk is really aimed at documentation maintainers um as well as new contributors. So cncf is a community of open source projects, and it's really really great that it's here, um but as far as an open source project goes, there is no dedicated support team. There is no sales team and there are no dedicated technical writers, unlike in a private company.

A

um This is not to call out any of the partner organizations that we work with, because what those partner organizations do staff is amazing, and we thank them for it. um It's more to say that the work that gets done is what the community chooses to contribute to and if we don't choose docs the docs don't get done and there are consequences for that. As we saw previously, um people look for projects that are well documented, especially in open source, because they don't have a company to fall back on.

A

So it's really important that those docs are well maintained.

A

So this is a talk not necessarily about documentation maintenance, though it's about how to become a really great documentation, writer- and I think we can borrow some ideas from english literature in our uh journey to become a great writer. So this is the hero's journey. uh It represents an archetypal story um in english literature. We think of the idea that most stories tend to follow a few different archetypes with a few different um variations.

A

The hero's journey is a really common one. Your hero is given a call to adventure, they meet a mentor, they go through some trials and tribulations and through those they gain the skills to return to their homeland uh and and vanquish an evil that they were maybe unable to conquer before their journey, um so they returned triumphant, but invariably changed by their experience um and heroes. Journey really applies to our users journey as they go through the documentation.

A

So we'll be using this as a bit of a framing device to talk about how to write good docs from your user's perspective.

A

So, let's start at the beginning, the college of adventure, a little bit of writing code, is a great example of what your user is thinking as they approach your documentation so famous story, little red riding hood is a very beautiful young woman, uh she's going to bring her grandma some food and she has a bit of a walk through the forest to get there. um I think this is. I don't think this is a story that people are unfamiliar with.

A

um When we think about this in terms of documentation, then we can take away exactly one thing, which is your user always has a goal, and your first task is to understand what that user goal is.

A

If your user were perfectly clever and smart and wonderful, they would have no reason for coming to the documentation. Invariably, though, they're here and now, we need to understand why, so that we understand what we need to write, there's a few different ways that you can go about learning what your users goals are. The first is obviously talking to your users.

A

If you have community managers or dev devrels or product managers or program managers. These are great people to start identifying that user need, um but not every project has those. So another way to go about. This is to keep track of questions that have been asked repeatedly or keep track of bugs that seem to come up time and time again in the slack channel.

A

What this usually indicates is a need that a lot of people are facing and if you write that down you're going to have pretty effective documentation for some subset of your users, the final thing you can do is as you're planning your development story. Ask yourself what the documentation is going to look like one of the hardest parts about writing documentation.

A

Is that as you develop something you become such an expert in the thing that you're creating that it's hard to zoom back out and think about what it would be like for a beginner. um So if you can bring that part forward that zooming out forward to before you start your development um you'll have a much better picture of what somebody needs to know than you will at the end.

A

um So this is what I want to talk, and I really want to talk about new contributors as well, though, which is you are invaluable to the development process for documentation for people here, because you have the beginner's eyes where, as we just mentioned, it's really easy to lose those as somebody who's working on a project. um So there's a number of different things that you can do that are really really helpful to project maintainers.

A

The first is to submit github issues and to open documentation. Pr's I've not met a project to date, which is unhappy to receive a documentation pr, um provided that the content is well-rounded and focused. um The next thing that you can do is to start talking to the project team and say hey well. I was trying to execute on this use case or this scenario. Would this be a good tutorial? Would this be a good blog post and maybe start working with them, um and the third thing is to cherish your beginner's mindset.

A

I think that people are often a little bit afraid to approach open source maintainers with questions and to be perfectly clear. The maintainers don't owe you an answer.

A

However, you only get to be a beginner once and sometimes those questions are invaluable and super useful to those maintainers in creating good content. So don't be afraid of asking that question and don't assume that you're the only person who's having that problem, because in most cases, there's somebody else as well.

A

um So let's talk about some common user goals for documentation um in general. uh These are ones that I've seen come up in my career over and over and over again. So I think I'm pretty confident in saying uh that they're they're in play here for cloud native, um so some common user goals when somebody's looking at the docs um evaluating new tech stacks to implement at their company.

A

This is surprisingly common um and a super underserved need in most documentation sets um most companies don't have great feature lists for their projects and most open source projects don't have great feature lists. Either people look at your documentation to evaluate whether this is something they want to use or not.

A

Another thing, that's really common is sort of learning. Just generally speaking, like they're they've started to use your project at work, and now they need to be an expert in it overnight. um Passing certification exams is another big one um supporting an existing system.

A

We are super lucky here at um the cncf and that cloud native is becoming super ubiquitous, and that means there are a lot of people looking at your documentation, supporting your thing in production and, finally, somebody's developing a new feature for their own company um and they're, looking at your documentation to solve a specific problem that they are currently facing.

A

um So the great thing is that documentation can meet all these needs and more um when we talk about evaluating text, apps concept docs are invaluable in that regards. um In regards to general learning to supporting um existing system, api references are super useful.

A

um Once again, on sort of passing certain exams, tasks and tutorials and cookbooks are a huge reference for that particular audience and um for the person who really just needs the answer to something specific, um generally being well organized in your documentation or having good information architecture as well as making your docs really searchable um is super helpful to the person who wants to do that.

A

So we've been talking at a high level now, and so, let's, let's dive a little bit deeper, um our hero has heard the call to adventure. They are in your docks. They want to find the solution to their problem or the end means to their goal, um and now they enter this middle stage of the hero's journey, they're facing trials and failure.

A

um So this is a greek vas depicting hercules slaying the hydra um hercules is. His story is famous for the many trials that he had to go through to regain his godliness, but in each of those trials he had to acquire new skills and gain new competencies in order to accomplish his goals and your user is exactly the same, we need to give them the skills with documentation because, as I mentioned, for an open source project, there is no support team. For that there is no sales team.

A

There is no marketing team, it has to come from the docs.

A

So luckily, as a technical writer, um I can tell you how to explain anything you ever want ever um and how to do it really really. Well. All it takes are three simple parts.

A

First, you have to explain the concept of something to people at a very high level. What is this thing? What does it do, and why do I, your user care?

A

The next is a task. So, okay, I understand your thing now now. How do I use it? I have a goal. I want to accomplish my goal. How do I use it, and can you tell me about any pitfalls I might run into along the way?

A

Finally, um I'm a user. I think I know how to accomplish my goal. After all those tasks, um but michael might be slightly different than the one that you mentioned. The task, so you need to give me some reference. Documentation show me all the things that your thing can do um and then I'll decide which of those functionalities. I need to use to solve my problem um and between these three styles of writing. You can explain anything.

A

um So, let's dive into this in a bit more detail, so concepts concept, topics, explain a feature at a high level. You can always tell a concept topic because they tend to use a very standard sentence. Construction, which is blank, isn't blank which does blank.

A

It's almost always the first sentence in the concept topic and that's how you know you're there in general concept, topics briefly describe or link to other topics related to the feature at hand, and they describe why a user might care about a feature or what the common use cases for using something are once again, I'm a user- and I have a goal- and I only care about that goal. So tell me whether this thing you're describing is going to make that call or not.

A

um So, to give an example. uh These are from the test, documentation and they're, describing a cell, and you can see that sentence in the very first sentence. A cell is a group of servers in network infrastructure, dot, dot dot, which typically does dot dot dot um in the second and third paragraphs we start describing and linking to other concepts that somebody might need to know and further on it's a bit cut off in this screenshot. We start talking about what the common use cases might be.

A

The second component of really great documentation are tasks and in many ways this is kind of the meat of the sandwich.

A

Tests describe what a user can do with a feature.

A

You can always tell you're in a task topic when you start seeing things listed out step by step by step, they'll, often use numbers or bulleted lists another sort of good flag for knowing you're in a task topic.

A

Is you see a lot of code samples, um so anything that has like crud functionality create read, update, delete, um will typically end up being in a task topic, and you can also sort of tell you're in a task topic if the top, the the title of the page, has a verb in it or starts with the verb, um because these are about doing. um There are lots of different styles of task topics. A numbered list is just one of them. um Tutorials are another type of task topic.

A

Cookbooks are a very, very focused sort of task, which is. This is the specific use case and the specific code you need to do it um and similarly sort of example, apps, broadly speaking, fall under the idea of a task, because you are trying to help. Somebody accomplish something um one thing to caution, uh particularly around kind of fully featured sample code like sample, apps and cookbooks um is as much as you think, or want to feel uh that the code just speak for itself and it's standalone. I promise you it isn't.

A

I promise you, it isn't um at a minimum. You need to describe to people how they can take the code from github put it on their computer and make it work, um but in general, um at the very least, commenting your way through a sample.

A

App is a really really great way to help your users out um so back to the test stocks for an example, um installs and quick starts are almost always task topics um and once again, the desktops uh do a really great job of showing that kind of third paragraph and we've got a code sample and the rest of the page continues in this fashion.

A

So the very last type of topic that you need to describe anything um often seems like the least glamorous and often ends up being the most important, particularly if you're you're in a pinch- and this is reference, so references provide lists of all options for a feature.

A

The one you might be most familiar with are api references which describe all endpoints and accepted data for a feature. Another one are javadoc cell documentation, descriptions of command line interface, flags and what each one of them do.

A

Often, these are auto generated from code, though not always, and the thing to keep in mind when creating reference topics is that completeness and accuracy is the most important thing to a good reference topic, um which is why they're often odd or generated from code um people are are surprisingly forgiving of a task topic that maybe has one step which is inaccurate, but reference documentation is where you often go when something is not working the way it should um and you need to sort of troubleshoot your way through it, which means if the reference is not accurate.

A

It's very very frustrating to your most frustrated users, and you will hear about it.

A

So a great example of how to manage complex reference topics uh via otter generation was um executed by our one of our google season of docs interns last year. So shout out to felipe for doing amazing work on this, because now the kubernetes docs are auto-generated directly into our hugo site.

A

So we have our concepts which explain things at a high level. We have references which explain things in quite a bit of detail, and you have tasks which explain specific tasks, something somebody wants to do great documentation almost always has all three types you rarely see any of them alone. So to give an example of what that might look like, let's take another look at prometheus's documentation and we're going to zoom in on this querying section.

A

So this first topic under querying basics. That's the concept topic. This is where they're describing what is querying, how does it work, etc, etc. um Operators and functions are a mix of concept and reference, so they explain what an operator is and then what operators are available. So that's the reference part and similarly they explain what functions are and what functions are available.

A

Next. They have examples which, when you click into this specific page, um is really a bunch of very short tasks and finally, they have an htc api reference.

A

All three types of documentation complement each other and they really shouldn't exist in isolation. So this is a great execution of that idea.

A

So, let's, let's head back to our heroes, journey for a second we've gotten our users going on an adventure um and we've given them new skills and if we've done our jobs well now they can go back to the thing that they're working on and they can achieve their goal. They can solve their problem um so they're on this part of the hero's journey. They have had a change, they've received a gift and they are returning.

A

So much like jack here, so this is an image from jack and beanstalk by the way um which, if you don't remember the plot, uh a lot, a giant has been stealing things from jack's family for quite some time. So he uh is given some magical beans. um He he plants them and grows a large beanstalk, and then he takes his stuff back from the sleeping giant um and he sneaks off and that's what your user's doing at this point in the journey as well.

A

They have what they need, but is that the whole story, because again, if you've read jack and the beanstalk anytime recently, the story doesn't end with jack. Sneaking off great documentation shows its users where to go next, um and it does this in a number of different scales. So you can organize the entire docs set along with user flow, which is what is the beginning for your user, the middle and the end, but it also does it at a much smaller scale, which is in an individual piece of writing.

A

So within that document um the beginning is usually the concept and then the middle is some task topics and then the end is a reference.

A

But what comes after the reference when you've imparted all the knowledge that you need.

A

Some well curated learn more links, never go out of style. Asking for feedback is we found it marginally still in the kubernetes community, but I I wouldn't re-implement this on a new site, um but never assume that your users journey is done just because they've reached the end of the page.

A

um My way of wrapping things up and to bring this back kind of for the new contributors documentation is a team sport. um New contributors and end users are kind of key to great documentation um and to kind of bring it back to hercules uh in this boss, you'll notice. On the left hand, side hercules actually has a friend here.

A

So while hercules is out front, fighting hydra, his friend is helping at the back and that's what you can do for project maintainers as a new contributor, um as I mentioned before, it's really easy to get super deep into something and super technical and suddenly lose sight of what it's like to be. A new user.

A

So a great way to start contributing to open source and to start contributing to cloud native communities is to start opening documentation tickets because they don't assume they'll, know um and your contribution could be really valuable in that regards.

A

So thank you very much for your time. Everybody has been lovely to chat docs with you. um I will be around at the end of this presentation to ask some questions live. um Here's where you can find me um if you want to get involved with um cncf projects.

A

Looking for doc's help join us at the cncf tech docs office hours, if you're a maintainer look out for the emails telling you where these are going to be, I and the other technical writers here at the cncf hold monthly meetings where you can ask us any question about documentation, you want and we'll try and help you out as best as you can.

A

If you are a new writer and you're looking to help out, I encourage you to drop into a project's community meetings and see whether it's to see um if you're, looking for something a little more structured, kubernetes sig docs is our biggest documentation community and they are the most well equipped to help new um contributors.

A

And if you want to talk more at me, I'm going to be hanging around in the cncf slack for another little while after this talk- and you can find me on twitter at slothstorkin. Thank you so much for your time.