📖👀 Let’s use readthedocs.org for Hoodie

[gr2m]

The current documentation at http://docs.hood.ie/ is desperately out of date and becoming an ever growing problem and cause of confusion, as it still references the old Hoodie which we no longer maintain. I started with a documentation for the new Hoodie at http://docs.hood.ie/camp/, but it’s not much of a help.

For a long time now I’m a big fan of http://readthedocs.org/, so I used the opportunity and created a dummy repository to see how it would work to use it for Hoodie. Here is the current result: http://hoodie-test.readthedocs.io/en/latest/index.html

My main motivation is to to become more welcoming towards people passionate about documentation, and Read The Docs has a big community. I highly recommend to listen to Episode 5 of the fantastic RFC podcast, which features Eric Holscher, the founder of Read The Docs, Write The Docs and just an overall amazing human being.

Read The Docs has – of course – a great documentation itself: http://docs.readthedocs.io/en/latest/. It is very powerful. Among other things it has great integrations with GitHub, which means each time we would push to master branch of the hoodiehq/hoodie repository, new documentation is generated. It also supports versioning out-of-the box which works perfectly with our semantic-release setup. And it support translations, including integration with Transifex.

I also like very much that the documentation will become part of the hoodie main repository, which will make it simpler to keep both in sync and will us allow to enforce workflows that would not release new feature or breaking versions unless the docs/ folder is updated, too.

Thinking about downsides, http://readthedocs.org/ is using Python and Sphinx which I personally am not familiar with myself, but people were super helpful to help me get going, including Eric himself :) Another downside is that the docs use ReStructuredText instead of Markdown, but that was the strong recommendation of people from the Write The Docs Community. It’s not that much of a learning curve though, but is much, much more powerful in terms of tooling appreciated by people writing documentation.

Please give this a thumbs up if you like it, or comment below if you have any concerns.

I would really, really like to go ahead with this, as I see a growing frustration of people new to Hoodie that end up using the old Hoodie version instead of the new one.

ping @hoodiehq/maintainers

[varjmes]

@gr2m I totally support this move!

[varjmes]

We'll need to write a guide on how to get set up to maintain the new docs, but apart from that I see no problem.

[janl]

+1 let’s do this

[gr2m]

w00p http://hoodie.readthedocs.io/en/latest/ thanks y’all! I made a follow up issue to add documentation for contributing to / maintaining the docs @Charlotteis