Welcome to the Write the Docs documentation 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. Here are some areas we think could use some work:

  • A high-level introduction
  • Reorganization
  • Your ideas!

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.

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 commmunication. 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. Also try to add at least 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, here’s a good place to get started:

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 just 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.

Community

For help, questions, or discussion, the Write the Docs community is available here:

You can also check out the main website for a list of local meetups.