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.
Last updated
Was this helpful?
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
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.
It’s seen as being a big barrier to participation, adoption, and contribution.
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.”
Open source projects, they’re not dying, but they are under-resourced, not very well-documented, and they don’t attract diverse contributions.
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.
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.
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.
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.
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.
