Contributing Documentation

Why Should You Contribute?

The Cloud Foundry documentation relies on contributions from the community to remain accurate, complete, and consumable.

Reasons to contribute to the Cloud Foundry documentation include:

  • You have noticed that a topic is incorrect or incomplete.
  • You are developing a new Cloud Foundry feature, and want to tell users know how to use it.
  • You are a good person, and you want to help your fellow humans.
  • You hate the idea of someone else having to go through what you just went through to figure something out. Such a waste; so inefficient.

How Can You Contribute?

The content for the Cloud Foundry documentation lives in several GitHub repositories within the cloudfoundry GitHub org. Each topic is represented by a source file in Markdown/HTML/embedded Ruby (html.md.erb) format.

Follow the procedures below to consult best practices, sign the Contributor License Agreement (CLA), and contribute to the documentation by submitting a pull request or raising an issue.

Step 1: Consult Best Practices

The Cloud Foundry Documentation Team reviews and revises all contributions. As a result, the team recommends that contributors focus on providing correct and complete information, and not worry about style and structure.

If you want to adopt best practices for documentation, keep in mind the following:

  • If your contribution is larger than a small correction, put yourselves in the shoes of a novice and read through it. Revise the text to answer any questions that might occur to a less experienced user.
  • Who needs this information? Are they a developer or a platform operator?
  • What are the specifics that a user needs to know in order to understand and perform the task? Instead of “the instance” or “the cluster,” explain the instance or cluster of what. Instead of “revise the code to…” explain where to revise the code.
  • If you’re giving instructions, include why you would want to do what you’re describing. What’s your specific situation, and what result do you seek?

For further guidance, contact the Cloud Foundry Documentation Team at cf-docs@pivotal.io or through our #cf-docs channel on the Cloud Foundry Slack.

Step 2: Sign and Publicize the CLA

If you plan to submit a pull request, you must have signed the CLA as an individual or publicized your membership with an organization that has signed the CLA. Perform the following steps:

  1. Complete and sign the appropriate CLA, either individual or corporate.
  2. Send a scan of the CLA to contributors@cloudfoundry.org, as instructed in the CLA. When sending the individual CLA, provide your GitHub username. When sending the corporate CLA, provide a list of GitHub usernames that can make pull requests on behalf of your organization.
  3. Publicize your membership in the appropriate GitHub org.

If you do not have a CLA on file with the Cloud Foundry Foundation, the cfdreddbot notifies you after you submit the pull request.

If you receive the cfdreddbot notification, but are confident that you are already covered under a corporate or organizational CLA, then verify that you have publicized your membership in an appropriate GitHub org.

Step 3: Contribute

You can contribute to the documentation by submitting a pull request or raising an issue.

If you have identified a problem with the documentation, and know the required content change, submit a pull request.

If you do not know the required content change, file a GitHub issue against the repository that contains the content.

Option 1: Submit a Pull Request

Perform the following steps to contribute to the documentation by submitting a pull request:

  1. Navigate to the topic that you want to modify.
  2. To locate the GitHub source file that contains the content for the topic, scroll to the bottom of the page and click Create a pull request or raise an issue on the source for this page in GitHub.
  3. Click the pencil icon in the upper right to edit the file in GitHub.
  4. Make your desired changes.
  5. Under Commit changes at the bottom of the page, enter a description of your change and click Propose file change.
  6. Click Create pull request.

Option 2: Raise an Issue

Perform the following steps to create an issue on a GitHub repository:

  1. Navigate to the topic that you want to modify.
  2. To locate the GitHub source file that contains the content for the topic, scroll to the bottom of the page and click Create a pull request or raise an issue on the source for this page in GitHub.
  3. Click the name of the repository where the topic is located. For example, docs-deploying-cf.
  4. Click the Issues tab.
  5. Click New issue.
  6. Enter a title for your issue, and in the text box, describe the issue and provide links to the affected topic(s).
  7. Click Submit new issue.

How Can You Preview Your Documentation Changes?

The Cloud Foundry Documentation Team uses the tool Bookbinder to publish the Cloud Foundry documentation.

The instructions below explain how to use Bookbinder to preview your documentation changes locally. But you do not have to install or use Bookbinder in order to contribute to the Cloud Foundry documentation.

Perform the following steps to preview documentation changes with Bookbinder:

  1. If you do not already have a workspace directory within your home directory, create one.

    $ mkdir ~/workspace

  2. Identify the content repository where your documentation lives. For example, https://github.com/cloudfoundry/docs-cloudfoundry-concepts.

  3. Clone the content repository. For example:

    $ git clone git@github.com:cloudfoundry/docs-cloudfoundry-concepts.git

  4. Return to your workspace directory and clone the Cloud Foundry book.

    $ git clone git@github.com:cloudfoundry/docs-book-cloudfoundry.git

  5. Change directory into the Cloud Foundry book.

    cd docs-book-cloudfoundry

  6. Run bundle install to install the necessary gems, including Bookbinder.

  7. Use Bookbinder to create a live version of your docs:

    $ bundle exec bookbinder watch

  8. Navigate to http://localhost:4567 in a browser and navigate to the route where your docs are published. For instance, http://localhost:4567/cf-cli/install-go-cli.html.

    Bookbinder automatically updates the live version of the docs whenever you make a change to the content repository.

Create a pull request or raise an issue on the source for this page in GitHub