Skip to content

Latest commit

 

History

History
126 lines (83 loc) · 4.69 KB

contribute.textile

File metadata and controls

126 lines (83 loc) · 4.69 KB
Raw

Contribute

The CarbonCalculated documentation team welcomes any and all help from the community. If you are interested in contributing to the effort, the information below will let you know how to do so and who to contact in order to get help and guidance.

endprologue.

How to Contribute?

First, you will need to fork the CarbonCalculated guides repository from Github. Go to https://github.com/carboncalculated/carboncalculated_guides and click the Fork button. Then, check your forked copy out onto your local machine.

$ git clone git://github.com//carboncalculated_guides.git

$ git remote add upstream git://github.com/carboncalculated/carboncalculated_guides.git

For each guide you write, you will want to create a new branch:

$ git fetch upstream
$ git checkout -b upstream/master

This will create a new branch for you to work on your new guide or to edit an existing guide. Next, you will need to get the guides executable.

If You Use OSX and Aren’t a Ruby Developer

The easiest way to get started with the guides on OSX is to download and install the guides pkg. This will give you the guides executable on your machine, and does not require you to have a C compiler on your computer.

If You’re a Ruby Developer

You can use the normal bundler workflow to develop the guides:

$ gem install bundler
$ bundle install —binstubs

For the rest of this guide, when the guides command is references, prefix it with bin. For instance, if you are instructed to run guides preview, instead run bin/guides preview.

Create Your Guide

Create a new guide .textile from the following template:

Guide Topic

This guide covers … After reading this guide, you will be able to:

  • Make a list of the things you will cover
  • This should be a relatively high level list
  • It should cover what the reader will know how to do once done

endprologue.

Topics Should Use h3

Each topic should use an h3.

To preview your guide as you write it, run the preview command.

$ guides preview
>> Thin web server (v1.2.7 codename No Hup)
>> Maximum connections set to 1024
>> Listening on 0.0.0.0:9292, CTRL+C to stop

Go to http://localhost:9292/.html in a browser. After making a change, refresh to see it update live.

Updating guides.yml

You will also want to update the main guides.yml in the root of the repository with your new guide. First, decide which section your guide will go under. In general, new guides will go under the Digging Deeper section.

Next, create a new entry for your guide. You will need to decide on a title and description. For the URL, enter the filename you used for your guide, without the .textile ending. An entry will look something like this:

index:
Carbon Disclosure Project Information:
– title: Using Carbon Calculated For Carbon Disclosure Project
url: carbon_discolure_project
text: “Learn how to use carbon calculated to produce a carbon disclosure project aware application”

Once you are done, push your guide to your fork:

$ git push origin

Next, submit a pull request from your repository. Make sure to make the pull request using the branch you used for the guide.

Some Guidelines

  • Guides are written in a modified Textile. Fro example,s take a look at existing guides, or some of the Rails Guides for some examples
  • For now, follow the Rails Guides Conventions.
  • Assets are stored in the assets directory.

What to Contribute?

  • We need authors, editors, proofreaders, and translators. Adding a single paragraph of quality content to a guide is a good way to get started.
  • The easiest way to start is by improving an existing guide:
    • Improve the structure to make it more coherent.
    • Add missing information.
    • Correct any factual errors.
    • Fix typos or improve style.
  • We’re also open to suggestions for entire new guides:
    • Contact the documentation team to get your idea approved. See the Contact section below.

What is the process?

  • Follow the instructions above to fork the repository and submit a pull request.
  • If you are a regular committer we will give you direct commit access.

Rules

  • Guides are licensed under a Creative Commons Attribution-Share Alike 3.0 License.
  • If you’re not sure whether a guide is actively being worked on, stop by IRC (information below) and ask.

Contact

  • Twitter: @carbonhq
  • Email : support@carboncalculated.com