On 2010 Apr 21, at 9:31 AM, Stuart Halloway wrote:
The second level header tells you the branch (e.g. master). On the
left hand side is a list of branches (so you can click on e.g. 1.1.x).
Wow, that is quite subtle. As you click into contrib from clojure.org
it isn't very noticeable.
It also isn't something you notice if you are, for example, clicking
through from the unversioned clojure.org pages.
An example at random:
Start at: http://clojure.org/macros
then click on the lazy-cat link, which takes you to: http://richhickey.github.com/clojure/clojure.core-api.html#clojure.core/
lazy-cat
and start browsing.
With your focus down 'into' that page you have no idea that you've
jumped into versioned information.
If you start as a beginner, as I did, the stuff on clojure.org is not
versioned (there is no master/1.1.x link in the side bar) and so
having version info appear only in contrib pages is not easy to
notice, particularly if you get there via links from the main page.
Some ways I see this might be better:
(1) make clear what master currently equals (right now it is 1.2
alpha)
That would help. Master is pretty generic.
(2) highlight the branch info more with css
Couldn't hurt, but it it'd be nice if showed in the page title too,
the sidebars are lost when scrolling down into the various pages.
(3) push the branch info into the top-level header (and page title)
Yup.
(4) The overview section for c.c.io could tell about the lineage
back to 1.1.
Not having been along for the ride since (nearly) the beginning,
having those breadcrumbs would be helpful to me.
Which of these (or what else?) would have helped you the most?
I think having the default, as Alex Osburne suggested, be the stable
release would have made my exploration of 1.1 a lot less painful.
And along those lines, distinguishing between core and contrib is
something that might be important to the maintainers, but not so much
to the users. And, very less useful to newbies trying to get something
useful done.
Trying to figure out that spit is in a contrib library and slurp
isn't? C'mon. I finally broke down and used google, and then when I
saw a thread back in '08 about that, and it still isn't addressed?
Really, easy file I/O is that unimportant to most clojure users?
Having a unified and comprehensive index of functions/macros
(annotated with core/contrib) would also go a long way to making the
clojure documentation environment a lot more useful. Oh, and then
there is the distinction between http://clojure.org/libraries and the
contrib libraries. Yet another place to look? Great, I really don't
have anything better to do than internalize these distinctions? (In
case you can't tell, having burned -hours- of spare time trying to
find my way around docs has been exceptionally frustrating.)
At least for someone like me who is exploring on their own and isn't
getting paid to make this work, having to lose my train of thought for
5-10 minutes while trying to figure out if something is core or
contrib is hugely frustrating and demotivating. Then throw in a "wtf?
why isn't this working in the stable release" only makes it more so
when I'm looking at the wrong docs and didn't even know that there
were versioned docs.
If you want an example of the kind of structure that I do find
helpful, look at docs.python.org. How many times on that page do you
see that you're lookin at the 2.6 docs and that there are links to
others? I'm not saying to make an exact clone, but I think it is fair,
if I am going to complain about this, that I also provide, at least,
an example of something that works and has worked well for years. (I
come to clojure from Lisp and Python, not Java, so I don't have any
Java documentation familiarity to compare/contrast).
-Doug
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
