Welcome to the Write the Docs documentation guide¶
Contributing to the Write the Docs guide¶
If you want to help create an awesome documentation guide, you’ve come to the right place. Welcome! Please read on to understand what we’re trying to do here and how you can help make it a better project.
Ways you can contribute¶
The guide is meant to address all aspects of software documentation. Depending on what you’re comfortable with, here are the basic ways to contribute:
- Fork, branch, and submit a pull request
- Submit an issue. You can use issues to suggest new content, or to file bugs against existing content.
Where to start¶
The guide has its origins in the efforts of developers to understand and explain documentation to each other. Since then, Write the Docs has expanded its focus and its community. We’ve recently reorganized the guide to provide a clearer top-level structure, but there’s much work to be done. Feel free to suggest further changes to the organization. Here’s where we need your contributions:
- More API documentation content!
- Helping non-writers understand what makes good documentation
- Helping writers new to developer tools or docs-as-code workflows to understand these toolchains and workflows
- High-level discussions of common tools and toolchains. Please avoid advocacy here! But thoughtful presentation of specific use cases, how you solved them, what worked well, and what didn’t work so well, are most welcome. If you want to write this kind of topic, consider starting with an issue in GitHub, or contact one of the new guide editors.
If you didn’t find a topic you were looking for, file an issue in GitHub.
What to leave out¶
The guide is not a place to plug your favorite toolchain, even if it’s open source. If you want to include a page that describes a documentation problem you solved using a particular toolchain, great, but make sure that it’s of interest to a general audience.
If you want to add a new set of topics, consider where they would fit best into the rest of the guide. If it’s not obvious where the new topics should go, ask in Slack, or file an issue.
The main focus is general principles and best practices, and we’d like to keep it that way. This means no bikeshedding – arguing over minor points at the expense of major principles of clarity and communication. And do avoid preferential editing – offering only your personal preferences for dealing with a particular writing situation. If you recommend a particular word choice, for example, explain why it matters to the larger world of the audience you want to address.
What we expect from you, and what you can expect from us¶
We encourage contributions from experienced folks and from newcomers, whether you’re new to documentation, to software, to GitHub, or to Write the Docs. We expect you to respect the effort that’s gone into whatever the current state of the guide might be, and we’ll treat your contributions with respect in turn.
Keep your tone friendly and encouraging. It’s a good way to write docs in general, so practice with docs about docs!
Link liberally to resources that you find useful, but make sure to provide appropriate attribution. And make sure to add something about how or why you find them useful.
For anyone new to GitHub and Git¶
If you’ve never worked with Git and GitHub before, try these resources:
How to Contribute to an Open Source Project on GitHub is a great resource to help you get started.
For small changes, you can submit issues, which you can do in the GitHub interface, but for anything larger you’ll probably want to learn how to fork and branch, how to work locally (although you can do most things in the GitHub interface in your branch), and how to keep your fork in sync with the main repository.
If you really don’t want to deal with GitHub at all, we’ll take attachments or inline text emailed to guide@writethedocs.org. But we’d like to encourage you to learn some of the basic tools that we use.
Markup¶
Some of the current files in the guide are written in Markdown, and some are written in reStructured Text (rST). Either one is acceptable, although we’d prefer rST.
Community¶
For help, questions, or discussion, the Write the Docs community is available here:
You can also check out our local meetups.
