Contributing Guidelines

Getting Started

If you want to contribute to these guides, start by cloning the guides repo locally on your computer:

git clone [email protected]:codepath/android_guides.git
cd android_guides
git submodule init
git submodule update
cd guides

You can see all the docs as markdown files in the guides directory. Update your local copy periodically with the latest guides using:

git pull origin master
git submodule update

Make your proposed changes locally, then push them to your own github repository. Now you can submit a ticket to the issue tracker requesting a review of your changes so we can merge them in. Please be sure to include a link to your repo and describe what you've changed.

With this approach, submitting changes is as simple as pushing your guides repository which we can review and then sign off on the changes the guides repo. If you want to change the guides more easily, you can edit the wiki directly. The choice is up to your discretion but we recommend for small changes such as correcting typos that you update directly through the wiki.

Guidelines

The cliffnotes philosophy is all about cutting down the content keeping the guides lean and practical. In particular:

• Don't include long preambles, blocks of text or extensive vocabulary lessons
• Do focus on the practical and be to-the-point
• Do include screencaps and images (and even video) that supplements the content
• Do discuss third-party open-source libraries that save you tons of time
• Do put the code blocks first. Always include practical code samples
• Don't use elaborate examples that take way too much time to understand.
• Do mention the implications and practical conclusions you've made

Principles

The most important thing is to save people as much time as possible. Include the maximum amount of useful code that we can in the smallest amount of space and 90% should be code in most cases. A few key principles to keep in mind:

• Have short introductions that explain the reason why the concept matters
• Always share references at the bottom of the guide that cites all sources
• Feel free to use gists for large bodies of code you want to link to

Missing Topics

Check the issues for this repository to see what types of contributions would be most impactful. In particular, I will maintain an issue that contains the most important missing topics. Also look for items in the cliffnotes with the Needs Attention mark which indicates the guide needs some love.