Tornado: http://tornadoweb.org/ Django: http://djangoproject.com/ NOT Python.
Why, I really like Python's documentation. Did you mean that the Python documentation is NOT good?
Ask HN: awesome web-based documentation?
41–47 of 47 posts
Re: Ask HN: awesome web-based documentation?
#42No one mentioned Apple's docs? I find them pretty well-written.
Re: Ask HN: awesome web-based documentation?
#43Tornado: http://tornadoweb.org/ Django: http://djangoproject.com/ NOT Python.
Why, I really like Python's documentation. Did you mean that the Python documentation is NOT good?
I'm not crazy about the formatting, honestly. I prefer more conversational documentation, personally, and Python's documentation always reminds me of Javadoc, which I generally abhor.
I think the one thing that I dislike, if I had to pick out something in particular, is that they include a function reference inline with discussion about it. I'd prefer to see them separated, though I freely admit that may just be me being peculiar, rather than any particular deficiency in the docs.
Re: Ask HN: awesome web-based documentation?
#44http://us3.php.net/strstr -> The php docs have one redeeming quality that I wish all of them had: comments! Whenever there is odd behavior, a gotcha, a pitfall, it's always in the comments. No need to trawl through blogs and mailing lists.
I loathe PHP's docs for two reasons: - the colour choice; - the comments. The colour choice for code examples is orange on gray. This is almost impossible to read for colour-blind people. I have to squint to make out each character. I can't get in to a flow and read the code, I have to decode each character then put them together to read the snippet in its entirety. I don't think user-land comments have any place in…
PHP's comments are moderated, and I don't believe that a comment is even allowed on the page until it's passed at least some moderator's standards.
That said, I think the comments absolutely belong there, as it's typically where I find the gotchas that don't make it into the language docs. Comments like "you can use this function most of the time, but if you're foo, functionB() is faster for those cases" are invaluable in optimization, and are seldom well-published in official language docs.
What that means is that I can be a slow expert in the PHP language versus the years of experience it would take me to divine those truths working in another language.
Re: Ask HN: awesome web-based documentation?
#45Earlier quoted context omitted.
Agreed. It would also be worth considering using Stack Overflow-style voting for comments.
Pet weekend project / software as a service?
I know with Disqus comments you can sort by Most Popular or Highest Rated. Not sure if you can default to one of those.
Re: Ask HN: awesome web-based documentation?
#46Slicehost's documentation is the BOMB. I aspire to be like PickledOnion one day.
Re: Ask HN: awesome web-based documentation?
#47Nanoc has excellent, comprehensive documentation with great typography and style in the layout:
http://nanoc.stoneship.org/docs/
backbone.js docs are concise and easy to follow, also well designed: