My interest is general improvement of Clojure documentation. At the conj, I spoke with Zack Kim about helping to improve the state of the documentation. My goal was to contribute additional documentation for vars that are lacking, as well as clarifying some of the more confusing doc strings (actually as a result of our talk, Zack is adding some community features to ClojureDocs where we can all comment and discuss doc string and submit possible revisions). As I started looking over the docs, it occurred to me that it would be nice to be able to format the strings (code formatting, bold, italics, lists, links, etc.), as well as add images where appropriate (I thought it might be helpful to have some images for describing how zippers work, for example).
I wouldn't mind having these features for my own projects, but I think that Clojure as a whole could benefit from these improvements; anything to make it easier for newcomers to get up to speed. Chris On Thu, Oct 28, 2010 at 1:09 PM, Andrew Gwozdziewycz <apg...@gmail.com> wrote: > On Thu, Oct 28, 2010 at 12:19 PM, Tom Faulhaber <tomfaulha...@gmail.com> > wrote: >> In order to better inform my thinking here, I want to ask: "So what's >> the target here?" >> >> Are we looking to enhance Clojure's core documentation or do you have >> specific projects of your own for which you'd like these features? > > All of the above, but before core documentation is changed, there > should be proven value, which would come from other projects making > use of the documentation extensions. > >> For example, my rationale for images is that I want to be able to >> include representative output graphs in the Incanter documentation. >> >> The reason I ask this is that I'm trying to distinguish between things >> we're proposing because we'd like to use them ourselves in areas we >> control and things we're proposing because we'd like to change the >> overall way documentation is done (both reasonable discussions, but >> different). > > I'm in this for the overall betterment of documentation in the clojure > eco-system on the whole, if people find value in it (which I imagine > people would be ok with richer, non-gobbledegooked documentation, if > that can actually even be done). > >> One of the things I'm working on is making available a full dataset >> with all the Var doc in clojure format so you can pull sample doc >> strings (and other info if you want). This is important for testing >> autodoc extensions against the existing population of strings. > > Great! This will certainly be helpful in the future. > >> -- >> 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 > > > > -- > http://www.apgwoz.com > > -- > 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
