> For the complete documentation index, see [llms.txt](https://scribbles.devrel.page/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://scribbles.devrel.page/developer-experience/inspiring-and-empowering-users-to-become-great-writers-and-why-thats-important.md). # Inspiring and empowering users to become great writers, and why that’s important {% embed url="" %} Video {% endembed %} ## 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.