deanmalmgren/flo — pull request #54 by deanmalmgren (2014-04-23 21:26:40+00:00)
Title: documentation readability

As a general comment, it would be better to start to make the documentation more digestible for John Q Public. This means that the documentation has to be geared more toward *use cases* rather than *features*. Features are important too, but they don't provide a compelling reason to use something. Perhaps a screencast would go a long way with this, but it'd be nice to make the documentation more digestable.

Having all of the documentation in the README.md has been convenient during preliminary development, but if we're going to announce this more generally to the public, it'd be nice to have a bit more thought out documentation solution. Ideally,
* it should have good SEO to make it easy to search from google to find answers
* it should be easy for anyone to improve the documentation. Markdown++ reStructuredText--
* it would be nice to keep the documentation coupled to the source code in the master branch to make it easy to add documentation with source code pull requests when its appropriate to do so. For example, when adding a new feature to the command line interface, it'd be better to not have to open two pull requests, one for the master branch for the source code and another for the gh-pages branch for the documentation
* it would be convenient to have the documentation autoupdate on push
* documentation versioning would be convenient, particularly if master will differ significantly with what is pushed onto pypi

The [github wiki](https://github.com/blog/774-git-powered-wikis-improved) makes it super easy for anyone to contribute to the documentation from the browser. In my experience with d3, this is a pretty decent way to answer questions from google searches. The downside is that the documentation is not bundled with the source code, so it requires the continuous maintenance of two separate options.

One perk to using [github pages](https://pages.github.com/) is that, with [jekyll](http://jekyllrb.com/docs/github-pages/)'s templating, its easy to maintain the documentation in Markdown. The downside is that github pages create a separate gh-pages branch that becomes a bit of a pain to maintain separately, unless you [configure git to auto-sync the gh-pages branch with master](http://brettterpstra.com/2012/09/26/github-tip-easily-sync-your-master-to-github-pages/). The other downside is that, as far as I can tell, github pages aren't really setup for doing documentation versioning in a very sane way.

[readthedocs](https://readthedocs.org/) with [webhooks](http://read-the-docs.readthedocs.org/en/latest/webhooks.html) would be pretty amazing as it accomplishes everything really well, except that it requires using [reStructuredText](http://docutils.sourceforge.net/rst.html) which is messy grossness. The only advantage to using reStructuredText is if it is likely that we'll ever add source code documentation for the `flo` package. This doesn't seem likely to me --- it doesn't seem as important to document the source code as only `flo` developers need that, and they will have to be comfortable with mucking around in python files anyway. The only good news is that [pandoc](http://johnmacfarlane.net/pandoc/README.html) makes it really easy to convert the existing documentation to reStructuredText.

[viewdocs](http://progrium.com/blog/2013/11/13/viewdocs-hosted-markdown-project-documentation/) is also interesting in that it makes it really straightforward to write documentation in the master branch in Markdown, but it doesn't seem to do as good a job with SEO