Skip to content

Introduction

We have been discussing about a readme.io alternative for the documentation of our software products. The requirements are summarized as follows:

  • Documentation files written in Markdown
  • Documentation stored in a github repo accessible to developers
  • Support for versioned documentation
  • Support for web hosting on custom domain
  • Support for search on the web hosted documentation
  • Support for PDF export
  • Review documentation while editing it
  • Product professional looking documentation pages

We looked at several tools:

  • http://readme.com/
  • http://readthedocs.com/
  • http://gitbook.com/
  • https://pages.github.com

Our current choice would be a combination of the following tools:

  • https://www.mkdocs.org/
  • its theme Material for MkDocs (https://squidfunk.github.io/mkdocs-material/)
  • hosting in https://pages.github.com

This guide describes the setup and can be used as a template for new documentation repositories.

GitHub Documentation Repositories

We will create dedicated GitHub repositories for the product documentation. We currently envision the following:

  • github.com/eurotech/docs-guide: this guide
  • github.com/eurotech/docs-el: for Everyware Linux Documentation
  • github.com/eurotech/docs-esf: for Everyware Software Framework Documentation
  • github.com/eurotech/docs-ec: for Everyware Cloud Documentation

Checkout the documentation git repository you want to contribute to or create a new one. For testing purposes, check out the docs-guide repository and review its structure. 

git clone https://github.com/eurotech/docs-guide.git