Contributing to the Write the Docs guide¶
Welcome! The guides at Write the Docs are meant to address all aspects of software documentation. To contribute to a guide, read on to understand our guides and how you can help.
How to contribute¶
Anyone can contribute regardless of professional or tool experience. Contributions that respect our guide’s current effort and state are treated with respect.
There are several ways to contribute:
- Edit a single guide directly in the GitHub UI.
- Edit files using Git.
- Submit an issue to suggest small changes, new content, or to note bugs in existing content.
What to contribute¶
We especially need contributions in these areas:
- Tools and best practices for documenting APIs.
- Documentation best practices.
- Developer tools or docs-as-code toolchains and workflows.
- High-level discussions of common tools.
For help organizing a new topic within the current guide, ask in Slack, or file a GitHub issue.
Contribution guidelines¶
- Use a friendly and encouraging tone. It’s a good way to write docs, so practice with docs about docs!
- Attribute links and mention why linked resources are useful.
- Use reStructuredText (.rst) (Markdown is also acceptable).
- Focus content on general principles and best practices. Arguing over minor points impedes clarity.
- Avoid enforcing personal preferences. For example, if you recommend a word choice, tell the audience why it matters.
Additionally, follow these guidelines when discussing tools:
- Ensure your content is of interest to a general audience.
- Avoid advocacy and plugs about your favorite toolchain, even if it’s open source.
- Present specific use cases, how problems were solved, and what worked or didn’t work well.
- Consider to first file a GitHub issue or contact a guide editor at guide@writethedocs.org.
Editing a single guide via the GitHub UI¶
- In the Write the Docs www project, find the file for the content you want to improve.
For example, /docs/documentarians.rst
creates https://www.writethedocs.org/documentarians/.
- Review formatting guidelines for the file’s Markup style. For example,
/docs/documentarians.rst
uses reStructuredText (.rst). - Click the pencil icon to edit this file in your fork of the www repo.
- Make your edits.
- Click Commit changes….
- Click Propose changes.
- Click Create pull request.
Updating a guide via a pull request¶
If you’ve never worked with Git and GitHub, use this section to get started.
Before you begin¶
- Create a GitHub account.
- Download and install Git.
- Open a terminal window and follow the instructions to associate your
GitHub username with your local Git installation.
- In macOS: Open the Terminal app.
- In Windows: From the Start Menu, open Git Bash.
- In the Write the Docs www project, find the file name corresponding to an existing issue or page you want to improve.
For example, /docs/documentarians.rst
creates https://www.writethedocs.org/documentarians/.
- Review formatting guidelines for the Markup style the file uses. The example file above uses reStructuredText (.rst).
Create a pull request with your changes¶
In the GitHub UI:
- Fork the Write the Docs www project.
- Click Create fork.
- Click < > Code.
- Copy the HTTPS URL for cloning the repository.
In a terminal window:
Open a terminal.
- In macOS: open the Terminal app.
- In Windows: from the Start Menu, open Git Bash.
Go to a directory for storing the cloned repository.
Type
git clone
, followed by a space, and then paste the project URL:git clone https://github.com/myname/www.git
git clone copies files from GitHub to a folder named
www
on your computer.Go to the
www
directory:cd www
Create a new branch:
git branch branch-name
Replace
branch-name
with a brief description of your proposed changes. Use dashes between words. For example:git branch important-typo-fix
.Switch to the new branch:
git checkout branch-name
In any text editor like Sublime Text or Visual Studio Code :
- Open the file you want to edit.
- Edit and save the file.
In your terminal window:
List the files you updated.
git status
If the list of updated files looks accurate, add any new or changed files to your local git project:
git add -A
Save your changes:
git commit -m "Your message"
git commit saves all of your edited files. Replace
Your message
with a description of the update you made. Learn how to write a good commit message.You can repeat the same process to add multiple commits to your branch.
Send your commit(s) to your GitHub project:
git push -u origin branch-name
Remember to replace
branch-name
with the branch name you created earlier.Create a GitHub pull request in the Write the Docs www project.
Community¶
The Write the Docs community is available for help, questions, or discussion: