Seek better docs hosting

[gene-eu-zz]

By receiving a few bits of feedback sounding almost equally (github's wiki is not well suited to read our style of documentation), before proceeding with even betters docs and tutorials, which are on their way, I'd like to hear your opinions, which documentation hosting platforms / documentation generation systems could work for us.

We could of course write our own tiny website-like thing, suited for our documentation needs, but I doubt this effort is worth it right now.

[mobrio]

What aspects of the GitHub wiki style are the most problematic?

[gene-eu-zz]

three big ones:

1. docs structure should be close to content, and it should evolve in detail as user navigates the content. e.g.
2. ability to embed custom JS handlers for some types of content, see multi-language switchable examples in soundcloud docs. there is JS for that, and we'd like to be able to use that, as some multi-language/multi-object explanations become really messy (forcing users to scroll through screens of code) quite fast
3. more control over docs looks (fonts, layout) and structure (even current tree structure is artifical to wiki's structure here)

I mean, people are not comparing us against ugly, default readthedocs or sphinx documentation. In life of modern developer, there is plenty of very high-quality designed and well-written docs. And if we could achieve at least some more accessibility by finding better design engine - we should do it.

good examples:

• https://parse.com/docs/ios/guide
• https://developers.soundcloud.com/docs
• https://stripe.com/docs/api (this is really magnificent in terms of multi-language, code, etc.)
• https://sendgrid.com/docs/index.html
• https://developer.github.com/v3/ (github's own docs, btw, show that some level of visual attractiveness is reachable within github's pipeline, question is how much effort will it suck out of us)
• https://coreos.com/docs/
• http://guides.rubyonrails.org/ (specifically for design!)
• http://pow.cx/docs/ (as the right way to show commented code we'd like to achieve somehow)
• https://stripe.com/docs (looks like readthedocs, but so much better)
• http://twitter.github.io/hogan.js/ (code vs description)
• http://docs.pylonsproject.org/en/latest/docs/pyramid.html (this is what is achievable with heavy modding of sphinx - still not enough, but very good)
• http://underscorejs.org/
• http://developer.android.com/guide/index.html (who would have thought, @secumod, right? but I like this)
• http://developer.postmarkapp.com/ (this one is very good)
• http://momentjs.com/docs/

[ignatk]

For docs hosting we might consider using GitHub pages: they support markdown, pretty fast, there are many beautiful templates out there. We can have any hierarchy and most of document generators generate html anyway. We still get all the git features for manipulating them.

[vixentael]

+1 to github pages. for the current moment let's use some existing tools instead of creating 'yet-another-tool'.

[gene-eu-zz]

Guys (and gals), sorry for creating this misunderstanding. I raised this as means to discuss what features we seek in documentation generation platform, not it's hosting. We can of course host them anywhere we want :)

[gene-eu-zz]

Right now, I'm considering this one - http://daux.io/ as possibly the best option, if we find ways to skin it properly.

[vixentael]

i like that 'Supports GitHub Flavored Markdown' in daux suport features list

[gene-eu-zz]

Started porting the docs to daux.io, anyway.