This Static Site

Feb 11, 2016 • Michael Myers

  • documentation

Static site generators have been around for a while. They have a great number of use cases but why are they the right choice for developer.xappmedia.com?

Leverage Existing Workflow

Documentation is really no different from source code, at their core they are just stylized text files. Thus we decided to leverage the same workflow we use for developing features and apply it to updating the documentation.

  1. Clone the Documentation Repository
  2. Branch
  3. Code Document
  4. Submit a pull request
  5. Peer Review
  6. Merge
  7. Deploy

Easy to Deploy

Jekyll, our static site generator, makes it tremendously easy to compile the CSS, HTML templates, and markdown into a static site.

To build simply run:

$ jekyll build

Then to deploy to production, we leverage the AWS CLI sync command:

$ aws s3 sync

Using these commands, we setup continuous deploy on our build server so whenever we merge a pull request, the production site is instantly updated. Automating this process allows us to concentrate on the documentation and not have to worry about deploying.

Customizable

We want the documentation to be easy to use and understand and also aesthetically pleasing. Since Jekyll leverages commonly used web technologies, we can easily push pixels by tweaking the CSS or quickly bring in a third party library with bower.io. It is a mature solution with extensive tutorials and articles (now one more), most problems we will face are already solved and documented.

Docs We Love

Documentation often offers you your first impression of a project. The following served as inspiration for our docs:

Technology We Use

A photo of Michael Myers
Michael Myers

VP Product