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.

Video

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.