Getting Started

Tools You Should be Comfortable With

The following are absolutely necessary for working on the Basho docs:

1. Markdown. You should be able to dream in Markdown. You can start with this tutorial. Beyond that, read through a fair amount of the Basho docs source to familiarize yourself with table syntax and some of the other more advanced things.
2. Git/GitHub. Reading the entirety of the very good (and free) Pro Git book is a great place to start.
3. One of the many Git-based merge tools, as merge conflicts are somewhat rare but do pop up from time to time
4. HTML. Although the vast majority of what you write will be in Markdown, there are times when you'll need to work in straight-up HTML. The most prominent example is the configuration files doc.
5. SLIM. This is the templating language used for most of the HTML templates that power the docs. You won't need to modify these templates very often, but when you do, make sure that you learn SLIM and do it carefully, because SLIM is very picky and will punish you for the slightest syntactical transgression.

A solid grounding in the following will not be strictly necessary but couldn't hurt:

1. CSS/SASS. You probably won't need to modify the site's aesthetic all that much, but you may run into issues with small things that need to be addressed,.
2. Any number of programming languages. Adding code samples can help make the documentation far more practical. B
3. ERB. This is a Ruby templating system that's used in a few places in the docs. It's really easy to understand and may come in handy at some point. Tutorial.

Running the Docs Locally

While not required to make textual changes, running the docs locally is incredibly useful for seeing how things will look when deployed.

Ruby

Currently we're working against Ruby 2.1.5.

Optional: rbenv (or similar, such as RVM)

1. Install rbenv
2. Install ruby-build
3. Install Ruby 2.1.5: rbenv install 2.1.5

Required: Gems

1. Change to the directory containing your local checkout of the basho_docs repo
2. Install Bundler, if you don't already have it: gem install bundler
3. Use Bundler to install the basho_docs gem dependencies: bundle

Middleman

Middleman is the tool we use to generate our documentation.

Generating the Files

To generate the static files:

bundle exec middleman build

Viewing the Files

You can use middleman to run a local web server to view the site:

bundle exec middleman

This will start the documentation site on port 4567. Go to localhost:4567 in your preferred web browser, and there they are.

One nice thing about running the docs locally is that Rack watches for changes in the docs' content, so you can change something, save the file, then go to your browser and refresh to see what it looks like. Not everything happens automatically that way, though. If you make changes to the left-hand nav, for example, you'll need to stop the server and start it again to see those changes. If you make a change and it's not showing up in the browser and you're not sure why, try restarting the server.

Trap Context Error

This is extremely annoying but you can't stop the Middleman server used for running the docs using Ctrl-C the way you can stop similar processes. Instead you have to kill it manually. A convenient way to do that:

sudo pkill -9 ruby

If you find a way to fix this, you win 1 googleplex of cool points.

Version Control

The Basho docs use Git for version control and GitHub for Git hosting. There is a special basho_docs repo for our documentation. If you're unfamiliar with Git, establishing a solid understanding is absolutely essential. I recommend this tutorial to begin with, and the Pro Git book when you feel like you're ready to acquire more advanced knowledge.

The Basho docs use a branched workflow. This means that the master branch is deemed most up to date at any given point in time. All changes to master should be made via pull request.

A branched workflow goes something like this. You need to add some new documentation (or fix existing documentation), so you go to the master branch:

git checkout master

Once there, you need to create a new branch for your work. This would create a branch called fix_aae_docs:

git checkout -b fix_aae_docs

We don't have a strict naming scheme for branches in the Basho docs, but it may be a good idea to provide as much information as possible, for the sake of discoverability. When in doubt, create a branch name that includes whether the branch is for a bug fix or a new feature, your initials, and a short descriptor. Here's an example:

git checkout -b bugs/lp/fix-ruby-syntax

Once your commit is complete, you can submit a pull request on Github.