DevRel Scribbles
  • What are Scribbles?
  • Index
  • Developer Advocacy
  • Developer Advocates
  • Life as a developer advocate
  • Modernising Red Hat’s enterprise developer program
  • Engaging 9-year-old software developers
  • Making 22-year-olds love 26-year-old software
  • Dogfooding developer products: gathering insights from internal hackathons
  • How far does your ethical responsibility stretch for the tech your devs create?
  • Outside the lecture theatre
  • How do you design programs for diversity?
  • Build the Platform Your Developers Actually Want
  • Measuring dev rel programs far beyond marketing activities
  • Developer Evangelism
    • Developer Evangelists
    • How to rock a technical keynote
    • The Art of Slide Design
    • The Art of Talk Design
    • The Art of Story Design
    • Dev events beyond 2021
  • Developer Experience
    • The Power of Content
    • Building a Developer Community in an Enterprise World
    • How to lose a dev in three ways
    • Developer relations, why is it needed?
    • The hierarchy of developer needs
    • GitHub is your documentation landing page
    • Docs as engineering
    • Commit messages vs. release notes
    • A11y pal(ly)- crafting universally good docs
    • Inspiring and empowering users to become great writers, and why that’s important
    • Solving internal technical documentation at Spotify
  • Community Management
    • Building community flywheels
    • DevRel = Community Management?
    • Creating high-quality communities
    • How to grow a healthy Open-Source community?
    • Managing communities at scale
    • Using community to drive growth
    • Useful community success metrics
    • Communities aren't funnels
    • How to mobilise your community during a pandemic
  • Managing a DevRel Team
    • Developer Relations + Product
    • Distributed developer relations
    • Understanding company goals
    • DevRel Qualified Leads (DQL)
    • Path to success for DevRel
    • How to move up in your organization
    • Four pillars of DevRel
    • Building your DevRel dream team
    • Managing the burnout burn-down
    • I messed up and I’m going to get fired
    • How to report on community relationships without being creepy about it
    • How to scale a developer relations team
  • Misc
    • Is developer relations right for you?
    • Tooling your way to a great DevRel Team
    • Planning your DevRel career
    • Success metrics as narratives
    • Get executive buy-in or else
    • Introduction to the AAARRRP devrel strategy framework
    • Strategy for developer outreach
    • Connecting dev rel and product
    • Performance DevRel
    • Ultimate cheat codes for healthier travel
Powered by GitBook
On this page
  • Summary:
  • Scribble:
  • Projects are dying
  • They’re not dying, they are under-resourced!
  • What things put people off?
  • How do we reduce the barrier to entry?
  • Good Docs Project

Was this helpful?

Export as PDF
  1. Developer Experience

Inspiring and empowering users to become great writers, and why that’s important

In this talk from DevRelCon London 2019, Jo Cook talks about The Good Docs Project and Google’s Season of Docs are working to make it easier to create excellent open-source documentation.

PreviousA11y pal(ly)- crafting universally good docsNextSolving internal technical documentation at Spotify

Last updated 3 years ago

Was this helpful?

Summary:

  • Find out the Problem.

  • Restate the problem

    • Finding more resources

    • Developers to miss out steps

    • Developers are familiar with the technical terminologies that they use.

    • Users that really know what their own expectations and needs are.

    • Users that are actually going to be using the documentation.

  • Figure out what puts people off?

  • Figure out a new solution.

  • Encouraging help with documentation for your project encourages empathy and improves diversity, both of which I think are very good things.

  • Good Docs Project

    • Identify all of the elements of good documentation that a project needs.

    • Establish a minimum viable docset.

    • Create a community of writers, users, and techies

Scribble:

Projects are dying

  • Open source projects are dying. I

  • On GitHub, 64% of those projects rely on just one or two developers to survive.

  • We then take into account that these people are really often doing day jobs and running these projects in their spare time, or in a very under-resourced way.

  • They’re not very diverse!

  • The ratio of women in IT is between 17 and 25%, but in open source, it’s between 0.1 and 5%.

  • What that means is that there’s a big pooling of talent, which could be being mined for participation in projects.

Documentation is often severely lacking

  • It’s seen as being a big barrier to participation, adoption, and contribution.

Getting help is tricky, and again

  • An open-source survey from a few years ago said that “Incomplete or outdated documentation is a big problem.

    • “93% of respondents spotted problems with documentation

    • 60% of those people say they rarely or never contribute.”

They’re not dying, they are under-resourced!

  • Open source projects, they’re not dying, but they are under-resourced, not very well-documented, and they don’t attract diverse contributions.

How do we go about fixing this problem?

  • Finding more resources

    • It is about creating more time for developers. It’s not about money.

    • How can we give developers more time to do what they want to do?

      • Whilst also improving project documentation‌

  • The GitHub Open Source Survey from 2017 identified that documentation is a really, really.….

  • Good way of getting people involved in projects,

  • Good way of establishing more inclusive and accessible communities.

  • brings in people from different communities, and encouraging contributions to more than just the code makes the project a lot more resilient in the long run.

  • Developers miss out on steps

    • Users are the best people to write documentation.

    • Easy for developers to miss out on steps because they’re very, very close to their software.

  • Developers are familiar with the technical terminologies that they use.

  • Users that really know what their own expectations and needs are.

  • Users that are actually going to be using the documentation.

What things put people off?

  • When you’re writing documentation, or when you’re trying to get them to help you when you’re trying to get them to contribute.

  • High barriers to entry.

    • What we’re talking about here is, is it easy for people to contribute to your documentation?

  • Users are more likely to help you ensure that your documentation covers these early, painful setup stages.

    • They’re actually not all that focused on the endgame.

    • They just want to get things done.

How do we reduce the barrier to entry?

Allow easy ways for users to contribute

  • Forms to make a pull request to make grammatical changes... really?

  • Preferably so they don’t need to install additional software.

  • Get their contribution live as quickly as possible.

    • These contributions, small contributions, lead to bigger contributions.

  • Acknowledge contributions, no matter how small they are, because they are important to the people that made them, and they’re important to your project.

Work with existing technical writers

  • There are lots of technical writers out there with huge amounts of subject matter expertise.

  • They’re not secretaries.

  • As developers, your best bet is to really make friends with those technical writing people.

  • Provide workflows that make it easier to write good documentation, and find all of those existing good practices.

Good Docs Project

  • Identify all of the elements of good documentation that a project needs.

    • Tutorials, how-tos, references, technical documentation.

    • Providing best practice resources and templates for each of them.

  • Establish a minimum viable docset

    • Designed to help you create a baseline set of docs.

  • Create a community of writers, users, and techies

    • Get practical tips and advice, and help for all parts of this project, of your process.

    • Aim of increasing quality and consistency.

Video