CONTRIBUTING.md

Contributor guidelines

These guidelines provide the general process for maintaining source code for the instructions and templates in the docs-starter-kit-external repository (repo).

• Repo description
• Updating and adding content
• Using writing guidelines
• Submitting your content
• Previewing changes

Repo description

This repo contains instructions and templates for use by those who want to create their own documentation repo.

• Content for user guides and API guides is written in reStructuredText, which is the markup syntax and parser component of Python Docutils.
• Content for How-To articles is written in Markdown.

For more information about the contents of this repo and how to get started, see the [Docs Starter Kit User Guide] (https://pages.github.rackspace.com/IX/docs-starter-kit-user-guide).

Updating and adding content

Contributions are submitted, reviewed, and accepted by using GitHub pull requests (PRs), following the GitHub workflow for this repository.

To update existing source files or add new ones, follow the GitHub workflow for this repository.

• Update source files by using the GitHub editor or any plain text editor.
• Format RST source files with reStructuredText syntax, and for quick syntax checking, try the Online reStructuredText editor.
• Format Markdown (.md) source files with Markdown syntax.

Using writing guidelines

When you add or update content, use the writing and style guidelines in the Style guidelines for technical content. Start with the guidelines in the Quickstart section.

Submitting changes

When you've completed your changes, submit a PR. Someone on the Information Development team will review your PR.

• Minor updates and corrections get a quick review to ensure that content is error-free and doesn't introduce other issues.
• More complex changes or additions require both technical and editorial review.

Depending on the review feedback, you might be asked to make additional changes.

After content has been reviewed and approved, the updates can be merged to the master branch.

Previewing changes

When you submit a PR, the build process creates a preview of your changes in a staging environment. After the build process completes, a message displays in the PR comments with a link to the content in a staging environment.

You can also build the project locally using the Sphinx documentation generator. For details, see Building from source.