Docs advocacy is dev advocacy

So, again, I am Erin McKean and I work on docs advocacy in Google's Open Source Programs Office. So, my job, and I think it's a fun one, is to help open-source projects have better documentation.

So, docs advocacy, if you haven't heard the term before, well, it's pretty new. Basically, docs advocacy is about bringing better documentation practices to the folks who often have the most power to make change, the developers. So, it's a developer-focused practice, just like DevRel, of encouraging better software documentation, whether that's through making good docs yourself, helping others produce docs through tooling or encouragement or, I don't know, the threat of force, or by creating a culture that enables good documentation to be produced.

And I think most people do understand that documentation is important, but I think people are often surprised to learn just how important the research says it is. So, for example, 72% of developers who were surveyed by Tidelift in 2019 said that established policies and documentation was a key decision factor when they were choosing open source.

93% of survey developers in the GitHub 2017 Open Source Survey said that incomplete or outdated documentation was a pervasive problem in open source. Now, I'm focused here on open source because that's what I work on, but I can't imagine that closed-source or proprietary software has less of a need for good documentation.

Lack of documentation was the top reason that developers, surveyed in the DigitalOcean 2018 survey, gave for deciding against using an open-source project. So, if you don't have good docs, people aren't even going to come through the door. So, survey after survey shows that developers care about docs and then they make choices based on docs. So, why don't we have better docs?

When I tell people that I work on making open-source docs better, they often tell me, "Great, we need better docs." And then I ask the uncomfortable question, which is, "What are you doing to help your projects, your products, your services have better docs?" As developer advocates, you're already developer-focused, you're in a great place to help the documentation culture of your product or your service or your project or really anything that you do.

And all the research shows, not just that documentation is important, but that, if you want to build good habits, those habits have to be everyday actions and not someday, sometime, once-in-a-while things. If you believe, and you should believe, that docs are important, then they need to be part of your daily practice.

They need to be an integral part of your developer advocacy work. Everything you produce should have a documentation component. Now, this is not easy. There's no like magic wand that you can wave to have great docs, or even any docs at all. But my favorite way for anybody, whether they're a developer or a dev advocate or a technical writer, my favorite way for anybody, at any level of experience, to start with creating documentation is by creating friction logs.

And I'll have a link to a great article by Aja Hammerly on friction logging at the end of this prezo. So, basically, friction logs are kind of low friction for you because you just do what you would normally do but you write everything down. So, specifically you write down what you tried, what worked or didn't work, what you did when things didn't work.

And there's always something that doesn't work. And then you just keep going. You try and you write, you try and you write, until you finish what you started. Or you give up. You can do this when you're putting together a tutorial, you can do this when you're putting together a talk. Why friction log? Because, especially as a developer advocate, sometimes we're so focused on showing the happy-developer path of proving that our tool or our service or a product or a project is good to use that we forget to model the process of problem solving that is part of all development work.

By writing and sharing our friction logs, we don't just demo our product or service, we also teach resilience. It's ironic that making things look easy actually makes things harder for some folks. I mean, honestly, if you did not have to stop and google something, when you were coding, were you really coding at all?

Now, you can also share your friction log with your product team, obviously, but it also makes great raw material for improved documentation, whether that's improving your tutorials or getting-started docs or even your troubleshooting docs. So, if you're committed to creating more docs and better docs and a culture of documentation and you're warming up with friction logs, what's next? I think it can be hard, when you're enthusiastic about something that you want to share with devs, to keep their goals in mind.

But thinking with the frame of documentation types can help. There are a couple of different documentation typologies out there but the one I think is the most helpful is the DITA one. Again, I'll have a link to this at the end. So, basically, they think about doctypes as whether they're tasks, or concept docs, or reference docs, troubleshooting docs.

And, of course, my favorite kind of docs, as a dictionary editor, glossary docs. But by thinking about, "Okay, who are my users? What are they trying to do, and what documentation type really fits what they're trying to do?" you help yourself focus and you help your users focus. And that means you're not trying to cram every sort of thing into the same dock that you're trying to write.

And, since we live in the magical era of hypertext, like seriously kids ask an old about what life was like before hypertext and the web, it was not great. Your task, your glossary, your reference doc, your troubleshooting doc, they can link to any of the other kinds of docs, whenever it's necessary.

And when you're thinking about what kinds of docs to make and you're not confident maybe about what the different documentation types like what they're actually like, what they're shaped like, there are lots of models available. The Write the Docs community is super great, very welcoming, helpful. Their Slack is really fun.

And you can also find templates for different kinds of documentation, its types plus use cases, with a little bit of searching with your favorite search engine. And there's an open source project, that I'm working with, called the Good Docs Project and they're working on this problem right now. This is the Doctopus, which is the mascot of the Good Docs project. We also considered having a Templatypus, for templates, but the Doctopus was just way cuter.

So, if you go to the Good Docs project on GitHub and you raise an issue in the templates repo asking for a flavor of template that you'd like to see, I will 100%, no joke, send you Doctopus stickers, COVID or no-COVID. I can send them anywhere in the world that American citizens are allowed to send mail, just raise an issue and tag me in.

Now, if you work on a project or a product that solicits documentation contributions from, you know, across your org, across your company, or from the wider external community, then you should really double down on templates. Templates and checklists and wish lists for the kinds of documentation that you like, they reduce friction and increase opportunity.

If there are folks on your team or in your org or in your company or in your community who have less social capital or less of a voice, checklists and wishlists and templates, any kind of documentation about your documentation lets them get started and make valuable contributions without having to ask for permission or without having to deal with the fallout from asking about things that everybody already knows.

So, okay, you're committed to writing and creating docs. You're committed to including docs in your DevRel practice, you're writing friction logs and making focus docs and using templates. What's next? Praise. Give lavish, unstinting, over-the-top praise. Praise any and all projects or products or tools or services that have good docs that you use because people do what they are rewarded for.

If some docs have helped you put together something, praise them in your presentations. Praise them in your tutorials and your blog posts. Call them out by name. People really do what they're rewarded for. And if your company has any kind of bonus program or recognition program, nominate people producing good docs.

Ask if you can actually do a special extra cycle for docs, just to raise awareness and to help people understand that they can reward people who are producing good docs. One other thing that you could do if you have spare development cycles, consider donating those cycles to improve docs tooling for your product or your project, especially if, by doing so, you can make it easier for people outside the dev team to contribute.

I'm totally biased because I help support the team that makes it, but, if you're looking for an open-source documentation site that runs right from a repo, take a look at Docsy. Docsy is an open-source theme for the open-source Hugo static-site generator, and it is specifically organized and set up to help people create technical-documentation sites quickly. So, again, the goal of things like the Docsy theme, of the Good Docs Project templates, of having a checklist or wish list in place is really to reduce cognitive load on people who might want to contribute by making it easier to do a reasonable thing.

Help people get started and get going instead of putting them through that process that, I think, we've all been through where we've spent so much time shaving so many set-up yaks that we're too tired to actually do the thing that we wanted to do in the first place. Now, I'm not saying that creating better docs is easy.

Anything that's worth doing is not effortless. But if you can, you can do what you can where you are with what you have. And if you just start, I promise you will make more progress than you think you will. Being docs-aware, thinking about docs when you're doing your dev-advocacy work turns like the power you have, as a dev advocate, to influence developers, to influence the culture of where you work.

It really turns it into a superpower. Creating better documentation is an incredibly effective way to scale your work. Now, the one thing that I do hear for folks, they kind of make this face at me, they give me a little bit of pushback. Some people in DevRel are much more comfortable giving talks.

Some people in DevRel like, you know, they like writing code but they don't like writing prose, so, sometimes I get some pushback that say, "I'm not a writer." And I totally understand, it is scary to work on things that you feel that you might not be great at. But, unless you are the Beethoven of software development, you have been expressing yourself in writing, in prose, at least as long or longer than you've been writing code.

And I'm here to tell you that your writing is fine. Now, how can I tell you that your writing is fine? Well, in my non-Google time, I run an extremely large, by number of words, online English dictionary and API called Wordnik. And I used to run American dictionaries for Oxford University Press, I have seen a lot of English. I also run the Semicolon Appreciation Society, and I'm so sad that we're not in person so that I can push these stickers on y'all.

So, if you want someone to tell you not to worry about your writing, or if you're writing in English and it's not your first language, I'm here to say that, in my professional language person's opinion, you are going to be fine. Do just a few simple things. Use templates. Ask trusted friends to give things a quick proofread. Most of all, accept corrections gracefully. And most people, most sensible reasonable people will overlook misspellings or a typo or two or subjects that are just having some mild disagreements with their verbs.

It will be fine. So, don't wait for the perfect time. Don't wait for the perfect tool. Don't wait for the perfect words before you start making docs better today. So, docs are important, developers tell us this again and again and again. You are in a great position to model good documentation practice to improve your DevRel practice by making docs like a first-class part of your practice.

You can bootstrap yourself, you can get started faster by using templates. And don't worry too much about your writing, as long as you thank people for giving you corrections and don't get mad about it, you'll be fine. And you can start today. So, I am very happy to answer any questions, either here or online.

I want to give you some links. So, friction logging, here's a link for friction logging from Aja Hammerly. Here's a link to the Darwin Information Typing Architecture to write the docs to the Good Docs Project and docsy.dev. And I am @emckean on Twitter. If you see the pink robot, that is not necessarily the mark of quality, but it does mean that it's me.

And thank you so much.

Tamao: Thanks, Erin. It was really great, helpful. So, yeah, I remind everybody, if you haven't joined our Slack channel, that's what I'll be monitoring for your questions for Erin. Kevin, did you have any questions to start with?

Kevin: I do. I do. I have a few questions. Erin, I don't want to put you on the spot but, after your presentation, I really want to hear you weigh in on the Oxford comma.

Erin: You know, that's a deeply personal matter for many people. I think that commas are like sprinkles on ice cream sundaes. Like they almost always make things better, you have to go really overboard to make things worse. And I think there are many places where the lack of a comma affects meaning but most of those are so hilarious that people notice it right away.

Like I'm sure you've seen the example where people say, you know, "I'd like to thank my parents, Stalin and JFK," and they don't have a comma after Stalin.

Kevin: I haven't seen that one but I have seen the "Let's eat grandma."

Erin: Yes, the "Let's eat grandma" one. Yeah.

Kevin: Yeah, "Let's eat grandma."

Erin: So, I feel like people should do what feels right for them and not beat up other people for what feels right for those folks.

Kevin: So, if you had like one opportunity to pass on, "Go look here for amazing docs," where would you point us?

Erin: You know, I don't think that that can be answered because docs are not like amazing without context. Right? Some docs are amazing for beginners, some docs are amazing because you really need to use that tool.

It's really like the chemistry that happens between the user, the documentation, the tool, and where they are that particular day. But I have to say that you can go a long way with docs just by putting yourself in the user's chair. I work mostly in the Node ecosystem, you would not believe the number of modules that I look at.

And they don't even tell me what the thing does. I'm not going to spend, you know, 20 minutes to 4 hours of my life reading your code if you can't tell me what the thing does in one sentence.

Tamao: So, I have a question. So, friction logs come up a lot during this event, which is great, and it's from different angles of course, Googlers. And, so, I'm really naive in this area, so, like is there a process where a product team and docs team sit together and they go through friction logs and decide like, "Well, we can fix this by fixing the docs here."

But understanding that it's also time and resources, you know, to write docs, you know, where do you decide like what's a better product decision? Like, "Why don't we just improve the UX for this situation versus spend all these hours on docs to kind of make up for the fact that there's friction?" Right? Like we haven't gone to that detail, so, I'd love to see if there's a process that you've been involved in where you say, "This product decisions is a doc decision," or in an order?

Erin: You're going to spend the time no matter what. You either spend the time on the product UX or you spend the time on the docs or you spend your time on customer service or you spend your time on DevRel time explaining things that aren't clear. Like products take the time that they take. And like it's up to you where you want to put your resources. Like, for example, if you have lots of devs and no documentarians, your first thought is going to be, "Let's fix the product."

But that only goes so far, right? Like you can't have something that's 100% UX and no documentation because nobody's UX is that great.

Tamao: But is there a ratio?

Erin: I think it also depends on the product and how many user journeys there are in the product. For a product where there's one core user journey and most of the friction is around people using it for something that's kind of off label, then maybe you don't want to change the product because it's going to muddy the core user journey for something that's like an all-singing all-dancing Swiss army knife.

Then you have to think about, "Okay, what are the user journeys we support in the product? What are the user journeys we support in the docs? What are the user journeys we like delegate our support to Stack Overflow?" Right? Like...it's really about what does it do and who is it for?

Tamao: Yeah. So, do you guys have that a little bit more systematized...like, you know, what do you decide...

Erin: Well, I mostly work in open source, so, I don't think you can apply the word "systematize" to open source. It's like 1,000 parades of 3 people each. But we do try to recommend like some best practices. And the thing I love most about friction logs is that, even if they're just for you, they help you. Like they are a gift to your future self.

I try to keep them for everything, I do like for Wordnik, because like there are lots of devops things that I do once every 18 months, if I'm lucky. I'm like, "Oh, shoot, now I got to update this? What did I do? How did I do it? What was the hard part?" And devops also...not devops, devops does help you systematize your thinking, but friction logs also help you systematize your thinking because you get into the habit of saying, "Oh, I tried this. What did it do?"

instead of trying like 50 things at once and muddling up all your variables.

Tamao: I see some people typing, but I'll let them finish. Especially like, you know, you work at Google, and thinking an enterprise level, there could be some groups. Like we have the extreme where people have seen Adam Fitzgerald now several times, including this time where everything's down to algorithms and calculations and, you know, like that's trying to get as precise as possible.

And I'm just wondering if there are some corners of Google that say, "Look, you know, the costs of all the labor are so high that it's worth sitting down and seeing if there's a little bit more of a fine-tuning of..." you know, "when it tips over a certain point, then we say it's a product problem versus a docs problem."

I'm just curious.

Erin: One of the great things about working at Google that I really enjoy is that it's so large and it's so diverse in terms of like ways people approach problems that I would not be surprised like if it's a multiverse. Like I wouldn't be surprised if you came to me and said, "Oh, Erin, I met this team at Google and they're writing all their docs in Esperanto." I'd be like, "Yeah, sure. I totally believe it."

Kevin: I was not expecting Esperanto to come up.

Erin: Nobody expects Esperanto. And yet it's the universal language, how ironic.

Tamao: Yes. So, I have some other questions but, Kevin, did you have any others? I didn't want to take up all the time...

Kevin: So, one of the things you said was that if you don't have to stop and google something, were you really coding? And I'm sure that's a paraphrase, but I really enjoyed that thought. And the question that comes to my mind is, as DevRel professionals, how do we make sure that, when you get to that point, you're googling something, that the docs is what comes up?

So that we have a marriage between the question, the friction point, and the answers. And where do you think that... I mean, when I think "docs," I think generally centralized documentation. But when I sit down to code something, I often find the docs that I use are on Stack Exchange.

Erin: Yes, or somebody's Medium post from two years ago or a deep, deep link to a GitHub issue. I think, as DevRel, one of the things that you can do is to try to raise something a couple of levels. Right?

So, if you see the answer to your question deep in GitHub issue, go up a couple levels to that project's docs and file a pull request to get the answer into the docs. Right? If you're on Stack Exchange or Stack Overflow and you find your answer, can you see, is this actually in the company's docs and can you link to the docs from Stack Overflow to help bring that chain closer together?

And, also, by linking from inside Stack Overflow, if somebody's paying attention to their SEO, they'll be like, "Oh, look at this thing over here. Maybe we should do some keyword analysis," or whatever it is. I'm not actually an SEO person, I just like, you know... And also it depends on your own search habits, your own search history, what search engine is your favorite. Like it's really hard to say that you will ever be able to miraculously get the right answer.

But you can help like lay breadcrumbs for other folks.

Kevin: So, at the very least, point out where the correct answer is?

Erin: Yeah. It's kind of like the boy scout principle, right? You should leave everything better than when you found it. Leave the campsite cleaner, leave the Stack Overflow answers tidier.