Hi all, (For those who don't know, I'm the one who maintains the autodoc API documentation.)
There are some great suggestions here and I'll try to pick up as many as I can. More useful branch names and having the branch in the title are no brainers and I'll try to get them in soon. One resource to use is the index included with each API. (See the index link in the left sidebar.) This has every function, macro and var in the whole library with a snippet of their doc. I find this to be pretty useful sometimes, especially when I don't remember which namespace something's in. I've always wished the Python doc had this feature! A couple things I've also been thinking about are building in a search capability and building a "super-index" of not only core and contrib but various other external libraries that would link back to their doc. Please also understand that Clojure is a young language and things are still very much under development. We're still understanding what our "best practice" is and how to approach it. As you point out, clojure.contrib.io is an example where we're not there yet, but it is happening. clojure.contrib.io is a precursor for a clojure.io namespace that will unify these things. Thanks for the ideas! Keep 'em coming. Tom On Apr 21, 8:39 am, Douglas Philips <d...@mac.com> wrote: > 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 betweenhttp://clojure.org/librariesand 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 > athttp://groups.google.com/group/clojure?hl=en -- 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
