Cloud Native Computing Foundation gRPC Conf 2020, 5 Aug 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Keynote: docs docs docs - Erin McKean, Docs Advocacy Program Mgr, Google Open Source Programs Office

Description

Keynote: docs docs docs docs docs docs docs docs docs docs docs docs - Erin McKean, Docs Advocacy Program Manager, Google Open Source Programs Office

A

All right well, thank you all for having me here today. I am um here to talk to you about docs, as you might have seen, and anyway hi I'm erin mckean.

A

I work on docs advocacy in google's open source programs office and my job and it's a fun one is to help open source projects have better documentation, so you might not have heard the term docs advocacy before, because it's pretty new, but basically doc's advocacy, is about bringing better documentation practices to the folks who often have the most power to make change and that's developers, so ducks advocacy is really a developer, focused practice of encouraging better software documentation and that's whether you start as a developer, creating better docs yourself or by giving other people the power to make better docs or just by creating a culture that values documentation so that better docs are produced.

A

Now I think we all know that docs are important, but sometimes people are surprised by just how important documentation is so in a recent tidelift survey.

A

72 of the developers that were surveyed said that established policies and documentation is a key factor when they decide to choose something open source and I'm focused on open source uh statistics here, because that's what I work on, but I can't imagine that close soft source software has less of a need for good documentation.

A

So 93 of surveyed developers in the github 2017 survey said that incomplete or outdated documentation is a pervasive problem in open source and lack of documentation was the top reason that developers gave for deciding against using an open source project in the digital ocean. 2018 survey so survey after survey after survey shows that developers care about docs and that they make choices and decisions based on whether there are docs. So why don't? We have better dogs?

A

um Well, it turns out that just telling people hey make better docs doesn't actually work. If it did work, we wouldn't have these problems.

A

If you really want to have improved documentation, you have to make it a priority, and then you need to signal that your priorities have changed, that you are putting docs higher up on the list of things that you need to do.

A

You have to back up those words with three things and essentially their tools, time and tribute, or you can use the word thanks instead of tribute, but I I like the word tribute because it also has you know monetary connotations which I like so I'm, starting with tools, because saying tools to developers is like waving a red flag at a bull. I know that the super devs I know y'all super devs in the audience are now setting up. You know visions of new and exciting, tooling dancing in your heads.

A

No one is immune from the siren call of new tooling I mean who among us has not spent three days automating a process that would have taken us an hour to accomplish manually.

A

It's so easy to think that you're gonna build the biggest and the bestest combination. You know, I don't know linter markdown parser and I don't know, insert your favorite buzzword here, doc's tool that the world has ever seen and I'm not here to tell you not to write your fancy tool.

A

I would be very excited to use your fancy tool if it has good documentation if it doesn't have docs, I'm not going to use it, but I will tell you that there's a much lower effort higher return tool that you can focus on something that you might not even consider a tool at all, and that is the lowly template and the humble checklist, checklists and templates answer some of the hardest questions in documentation.

A

Where do I start? What do I do? When am I done reducing the cognitive load on your documentation, contributors by preempting? Those questions with checklists and with templates is the best thing that you can do to get better documentation faster, combining checklists and templates with a wish list of documentation types, for example, making it explicit that you? What you really need is a tutorial for beginners or a guide to integrating your software with something else.

A

Really templates and checklists are the pre-chopped vegetables of documentation, sure you could tell everybody to freestyle it or to trap their own onions, but if you could make things easier for folks, why wouldn't you templates are themselves documentation about how to do documentation, they're they're meta documentation, and I think that one of the best and most overlooked uh benefits of templates and checklists is that they reduce friction.

A

If there are folks on your team who have less social capital, like maybe they're new, maybe they have less of a voice, checklists and templates and wish lists help them get started and make really valuable contributions without having to ask for permission or deal with the fallout from asking about things that you know, everybody already knows by providing clear instructions, a format for how things should look a wish list of things that you really want and a checklist for knowing when things are done, you'd be surprised at how much faster and how much better your project could be creating documentation.

A

Now, if you're looking for sample documentation templates, the good docs project is an open source project. That's working on this problem right now.

A

This is the doctopus which is the mascot of the good docs project, and if you go to the project, it's on github and raise an issue in the templates repo asking uh for a flavor of template that you'd like to see, I personally will send you, octopus, stickers, covet or no covid. Just add me to the issue I'm imakin on github. uh You will find me I'm in the repo but we'd really love to know what kinds of templates would be useful to you and would be useful to your project.

A

Another tool for better documentation is doxy, which is another open source project. The good docs project is an independent, open source project, but that googlers are heavily involved in uh doxy. Is a google developed, open source theme for the hugo static site generator, so it's so hard to say, hugo's static site generator generator quickly.

A

It's specifically organized to help people create technical documentation sites quickly and again the goal of these docs tools, whether they're a checklist, a template, a wish list or a theme- is to reduce cognitive load by making it easier to do a reasonable thing quickly, instead of saving in instead of spending so much time, shaving, so many setup yaks that you're too exhausted to actually do the thing that you started to do in the first place.

A

So, yes, you need to give people tools and there are plenty of tools that you can give folks even before you start writing your own. But what you really also have to give people is time. Docs can't be a nice to have we've seen from the research that they're way too important. For that, sometimes I think that documentation is in the same place. That testing was you know, 10 or so years ago.

A

Something developers asked other people to do late in the game if there was time, but we've seen how much better code is when testing is an everyday thing, why wouldn't the same, be true for docs build time for documentation into what you're doing, because even the most exciting interesting technologically spectacular feature is useless if no one uses it because they don't know how now tools and time are only part of what you need for good, docs and now we're getting to.

A

The third word tribute: what kinds of accolades, what kinds of rewards do you give to other contributors to your projects, and do you give those same rewards that same praise that same recognition that same feedback to your docs contributors?

A

And if you don't? Why is that when I tell the people, when I tell people that I I get to work on making open source documentation better, they often tell me great: we need better docs and then I ask okay. Well, what are you doing to help your projects? Have better docs, let me help you do the work that we all agree needs to be done.

A

I'm not saying that creating better docs is easy. Anything that's really worth doing, can't be effortless, but you can do what you can where you are with what you have.

A

If you just start, I promise that you will make a lot more progress than you think you will, but you have to have the tools to do it have the time to do it and you have to work to make sure that the work that you've put in is recognized now. There's one other thing that I wanted to mention that sometimes I get pushback from developers about creating documentation and that push back takes the form of, but I'm not a writer.

A

I understand it is very scary to work on things that you feel that you might not be very good at and documentation is public, it's very public, but unless you are the beethoven of software development, you have been expressing yourself in writing, at least as long or longer than you've been writing code.

A

And I'm here to tell you your writing- is fine.

A

In my non-google time, I run an extremely large counting by number of words online dictionary and api called word wordneck, and I used to run american dictionaries for oxford university press and I also run the semicolon appreciation society.

A

So if you want someone to tell you not to worry about your writing or even if you're writing in english- and that's not your first language, I'm here to say in my professional language person- opinion you're gonna, be fine. Use templates ask trusted friends to give things a quick proofread, and I cannot stress this enough. Accept corrections, gracefully and most people will gladly overlook a few misspellings, a typo or two or subjects that are having mild disagreements with their verbs.

A

If it means that they're going to get largely useful documentation, don't wait for the perfect time the perfect tool, the perfect words to get in the way of making your documentation better today, if, if you can combine being able to create good documentation with being able to create good software, if you want to increase your impact and the impact of your work, better docs is an incredibly effective way to do it.

A

You might even call documentation skills, a superpower, so, to recap, I hope, you're excited about getting started where you are with what you have today to make better docs stocks. Are important developers tell us this again and again and again, every time we ask developers what do they care about? One of the top answers? If not the top answer is documentation, but you won't get better docs until you provide tools and time and tribute to the people who are making them start by providing checklists templates.

A

Wish lists, use themes that are set up for documentation to remove the cognitive load to to get people over the hump of. Where do I start and don't worry too much about your writing. Just take the same amount of care that you would take if you were starting to code in a new language.

A

Double check ask people for help, but most of all start today.

A

um I've left some time for questions, but I wanted to quickly uh give you all some of the links that I mentioned um so the doxie theme you can see that at doxie.dev and that has a link to a working example site and also links to other sites live in the wild that are using doxy.

A

You can follow doxydocs on twitter. You can follow me on twitter. uh I do te tweet about tech, but I also tweet about weird word stuff, so brace yourselves um and you can follow the good docs project on github.

A

So thank you all so much for your time and attention today. Please feel free to reach out to me with documentation questions.

A

Please feel free to ping me at the good docs project and raise issues and ask for the kinds of templates and checklists you'd like to see we're just getting started so the more feedback we get the faster we go and thank you so much again for your attention.