I've wanted to work on expanded documentation for Clojure, too, both as a way to contribute something I think is needed and as a way to learn Clojure. To illustrate what I have in mind, I put together an example of new documentation for 'conj' located here (a read-only google doc, for now):
http://bit.ly/9YOvgP Try to imagine the information tastefully laid out with a lot of hyperlinking, category cross-referencing and additional organization à la the Clojure Cheat Sheet. Not only would it be a way to see example code, both toy examples and real-world examples, but also a way to tie together related functions/macros, explanations and/or outside linking for some of the larger concepts (like clojure.org sidebar topics, links to relevant videos, books?, etc.) The target audience I had in mind would be people who want to learn clojure and want to have an available reference more expository than the current API docs. Please note that I'm still learning Clojure and one or more bits of information at the above link may be incorrect! And it's still very unfinished; I know at least one of the terms used is incorrect ("items"? I whipped it together ...). I would welcome corrections and explanations, even if what I've produced so far is just a simple example of what could be. - Ryan Waters On Tue, Jun 29, 2010 at 9:34 AM, Angel Java Lopez <ajlopez2...@gmail.com> wrote: > Hi people! > > I love PHP documentation > > http://www.php.net/manual/en/ > > and its function reference: > http://www.php.net/manual/en/funcref.php > > Each function has a dedicated page, with detailed description, initial > examples. And visitors can add new examples or limit cases. Example: > > http://www.php.net/manual/en/function.array-combine.php > > And the documentation can be built in .pdf and other formats. I never need > an irc channel or send an email in a list to understand a function. Maybe > for other topics, but not to understand a function. > > That's the level of function documentation to match, I guess. And it's > pretty good in the non-function part: good explanation of language and its > usage. > > Angel "Java" Lopez > http://www.ajlopez.com > http://twitter.com/ajlopez > > On Tue, Jun 29, 2010 at 1:06 AM, cageface <milese...@gmail.com> wrote: >> >> Several people have suggested that usage examples in the docs would be >> helpful and this is something I often find myself wishing for. Are >> patches introducing examples welcomed by the core team? >> >> -- >> 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 > > -- > 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 -- 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
