search

clojure-grimoire / grimoire

Community documentation of Clojure
http://conj.io
159 stars 41 forks source link

Don't hide official docs #225

Closed alexander-rymasheusky closed 8 years ago

alexander-rymasheusky commented 8 years ago

I was searching for sorted-map from Clojure Cheatsheet site, and was redirected to Grimoire. The addition of user-generated documentation is really great, but the absence of official docs was bad. In particular I'm very used to seeing function signatures when searching for docs, and they were missing for sorted-map. It would be great if the official docs would till show even where user-generated docs exist.

arrdem commented 8 years ago

Hum. So in general, I disagree. The direction I'm trying to take Grimoire is to feature documentation written by myself and others which completely replaces the official docstrings. I think that doseq and for are good examples of how this can be an improvement.

You're correct in that this particular docstring's case the arities aren't mentioned. This is a data files bug which I'll fix in a minute.

As a more general matter, It's certainly possible to include the default docstrings in a "folded by default" section same as I do for the source code, however I'm concerned that this clutters the already in need of work per-symbol pages further to no clear end. Consider. Were the "official docs" block to occur before the examples, it'd be detracting from the examples which I consider to be the other major value-add of the site, and if I stick it at the end with the source code nobody will ever read it.

alexander-rymasheusky commented 8 years ago

Thank you. No disagreement about the point that user documentation will be better than official, and you do a good job here. The inclusion of official docs would be good for users like me, who were used to old doc pages and are now going to your site - and good for cases like this one, where data files are not yet correct.

In my view, a folded-by-default block after documentation and before examples is the best place to put it. One line is not a big deal of clutter; the user clearly sees that examples follow; he can scroll to see them all, or click to expand the section. (Incidentally, I think the same place would be better for Code block for the same reason. I wouldn't know about Code block's existence if you didn't mention it here, as I didn't scroll to the bottom of examples.)