I've gotten a lot out of Clojure: I can honestly say that learning
this language, and being part of this community has made me a better,
happier developer, and I wanted to give something back.
One of the pain points that I encountered when learning the language
was a lack of examples specific to the individual functions I was
trying to wrap my head around at any given time. So I took a whack at
the problem, and came up with http://clojuredocs.org. It's a site
that (I'm hoping) will fill this need by providing a centralized
examples database, along with solid search capabilities across both
core and third party libraries (core being the focus).
Implementation:
ClojureDocs.org is a rails site backed by MySQL, along with some
clojure code to pull the namespaces / metadata / source and dump them
into the database.
Highlights:
1. Documentation and source for Clojure core, contrib, and a few third
party libraries (random selection out of what I'm personally familiar
with, and whatever was on the github trends page that day).
2. Search for a var across the whole ecosystem or in a specific
library.
3. Per var wiki-style examples section.
4. Per var comments section.
5. Per var vars-in-this-var and this-var-used-in section (my personal
favorite). Looking for a real-world example of a specific function?
This is for you. For example, http://clojuredocs.org/v/1978, just
below the source section.
I'm treating this as an alpha, and I'd really like feedback as to:
a. How useful this would be to the community.
b. Specific likes / dislikes about this alpha release.
c. Feature requests.
I've set up a feedback mechanism directly through the site (User
Voice), which allows voting on specific posts. I'm also considering
setting up a google group for general discussion. Feel free to
contact me directly through email.
I took a first look and I have to say that the idea is genius and I love what you put up together this far. It is difficult to keep up with what's happening in the Clojure world, and this kind of central place to keep track of things was needed. The examples are also a strong point. I hope the site will grow with many people's contributions.
On Fri, Jul 9, 2010 at 4:32 AM, zkim <zachary....@gmail.com> wrote: > Hi All,
> I'll try to keep this short.
> I've gotten a lot out of Clojure: I can honestly say that learning > this language, and being part of this community has made me a better, > happier developer, and I wanted to give something back.
> One of the pain points that I encountered when learning the language > was a lack of examples specific to the individual functions I was > trying to wrap my head around at any given time. So I took a whack at > the problem, and came up with http://clojuredocs.org. It's a site > that (I'm hoping) will fill this need by providing a centralized > examples database, along with solid search capabilities across both > core and third party libraries (core being the focus).
> Implementation: > ClojureDocs.org is a rails site backed by MySQL, along with some > clojure code to pull the namespaces / metadata / source and dump them > into the database.
> Highlights: > 1. Documentation and source for Clojure core, contrib, and a few third > party libraries (random selection out of what I'm personally familiar > with, and whatever was on the github trends page that day).
> 2. Search for a var across the whole ecosystem or in a specific > library.
> 3. Per var wiki-style examples section.
> 4. Per var comments section.
> 5. Per var vars-in-this-var and this-var-used-in section (my personal > favorite). Looking for a real-world example of a specific function? > This is for you. For example, http://clojuredocs.org/v/1978, just > below the source section.
> I'm treating this as an alpha, and I'd really like feedback as to: > a. How useful this would be to the community. > b. Specific likes / dislikes about this alpha release. > c. Feature requests.
> I've set up a feedback mechanism directly through the site (User > Voice), which allows voting on specific posts. I'm also considering > setting up a google group for general discussion. Feel free to > contact me directly through email.
> Questions / thoughts?
> -Zack
> -- > 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+unsubscribe@googlegroups.com<clojure%2Bunsubscribe@googlegroups.com > > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
On Fri, Jul 9, 2010 at 2:32 AM, zkim <zachary....@gmail.com> wrote: > Hi All,
> Questions / thoughts?
> -Zack
Hi Zack, First off, I think it looks great, and it definitely seems useful when trying to find an example of a particular API call.
Few suggestions: 1. The headers for each section (Doc, Source, Example(s)) don't differentiate themselves from the regular doc text enough, maybe bold/underline/color them to make them show up more? 2. The links to the source code should link to http://github.com/clojure/clojure, I believe the richhickey clojure repo has been transitioned there. 3. I know non-confirmation logins are really nice, but should the site attract any spammers, you may want to look at adding an email account confirmation (since spammers could go nuts adding comments to pages).
Looks awesome, hope it gets some love from the Clojure community.
It's a great idea, and the site looks very good.
Two suggestions:
1. Move examples section above source code section
2. Add OpenID sign in support. Personally I'm instantly repelled by
sites asking me to create another account/password. And I'm sure I'm
not alone. Stackoverflow.com is a great example of how effortless it
could be to "register".
- Dmitry
On Jul 9, 1:32 am, zkim <zachary....@gmail.com> wrote:
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
> 2. Search for a var across the whole ecosystem or in a specific
> library.
> 3. Per var wiki-style examples section.
> 4. Per var comments section.
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> below the source section.
> I'm treating this as an alpha, and I'd really like feedback as to:
> a. How useful this would be to the community.
> b. Specific likes / dislikes about this alpha release.
> c. Feature requests.
> I've set up a feedback mechanism directly through the site (User
> Voice), which allows voting on specific posts. I'm also considering
> setting up a google group for general discussion. Feel free to
> contact me directly through email.
I've actually been thinking about this exact same kind of site for a
while now and I'm thrilled that I was too lazy to do it so that you
could do it instead. :)
One idea that I have that I think would be killer would be to provide
an API to look up one your examples at the repl so I could do
something like:
There are of course many variants of some functions and different
forms of use, so dealing with the best way to provide useful help
without an overwhelming number of examples is tricky in the repl, but
I think worth doing. Along with doc and source, I think example would
be a killer addition to allowing you to explore the libraries from the
comfort of your repl.
Alex
On Jul 9, 3:32 am, zkim <zachary....@gmail.com> wrote:
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
> 2. Search for a var across the whole ecosystem or in a specific
> library.
> 3. Per var wiki-style examples section.
> 4. Per var comments section.
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> below the source section.
> I'm treating this as an alpha, and I'd really like feedback as to:
> a. How useful this would be to the community.
> b. Specific likes / dislikes about this alpha release.
> c. Feature requests.
> I've set up a feedback mechanism directly through the site (User
> Voice), which allows voting on specific posts. I'm also considering
> setting up a google group for general discussion. Feel free to
> contact me directly through email.
I've told Zack that he is free to pull any examples from the wiki for
use on his site.
I don't know about collaboration beyond that. The wiki is open source
and written in Clojure; anyone is free to contribute/fork. At least
one person has expressed interest in making code contributions.
Zack, you had mentioned you planned to keep the source of your site
proprietary -- is that set in stone?
Justin
On Jul 9, 12:21 pm, David Nolen <dnolen.li...@gmail.com> wrote:
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
> 2. Search for a var across the whole ecosystem or in a specific
> library.
> 3. Per var wiki-style examples section.
> 4. Per var comments section.
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> below the source section.
> I'm treating this as an alpha, and I'd really like feedback as to:
> a. How useful this would be to the community.
> b. Specific likes / dislikes about this alpha release.
> c. Feature requests.
> I've set up a feedback mechanism directly through the site (User
> Voice), which allows voting on specific posts. I'm also considering
> setting up a google group for general discussion. Feel free to
> contact me directly through email.
On Fri, Jul 9, 2010 at 2:32 AM, zkim <zachary....@gmail.com> wrote: > Hi All,
> Questions / thoughts?
> -Zack
Hi Zack, First off, I think it looks great, and it definitely seems useful when trying to find an example of a particular API call.
Few suggestions: 1. The headers for each section (Doc, Source, Example(s)) don't differentiate themselves from the regular doc text enough, maybe bold/underline/color them to make them show up more? 2. The links to the source code should link to http://github.com/clojure/clojure, I believe the richhickey clojure repo has been transitioned there. 3. I know non-confirmation logins are really nice, but should the site attract any spammers, you may want to look at adding an email account confirmation (since spammers could go nuts adding comments to pages).
Looks awesome, hope it gets some love from the Clojure community.
Thanks all for your kind words. As to the specifics:
> The headers for each section (Doc, Source, Example(s)) don't
> differentiate themselves from the regular doc text enough, maybe
> bold/underline/color them to make them show up more?
I'd agree, I think the visual styling of the page will change a lot in
the near future based on feedback, for now I'll add underlining.
> The links to the source code should link to
> http://github.com/clojure/clojure, I believe the richhickey clojure
> repo has been transitioned there.
Will update.
> I know non-confirmation logins are really nice, but should the site
> attract any spammers, you may want to look at adding an email account
> confirmation (since spammers could go nuts adding comments to pages).
This is strictly for alpha, I'm currently going back and forth between
signups confirmed through email, or recaptcha (or both), but rounding
out the sign-up / login process is high on my list.
> This is great. I think the main thing is not duplicating effort. This and
> clojure-examples.appspot.com should really join forces.
> Having contributed a lot of examples to clojure-examples.appspot.com
> this week, I agree that it would be a shame to duplicate efforts.
I've been talking with Justin, and he's allowed me to pull examples
from his site (as well as given some great feedback). I'm definitely
all for a collaborative effort.
Thanks, Zack.
On Jul 9, 10:30 am, ".Bill Smith" <william.m.sm...@gmail.com> wrote:
I've put these suggestions up on the UserVoice page, I believe I got
all of them, but if I missed yours please add it yourself or let me
know.
Dimitri: I share your frustrations with having to remember yet another
login / password. Other than minor cosmetic fixes, improving the user
signup / login experience is at the top of my list.
Alex: Example lookup from the REPL would be awesome. As of now this
is a bit lower on the list until things stabilize around the site.
Side note: My responses don't seem to be showing up right away on the
mailing list, so they may appear out of order.
> Zack, you had mentioned you planned to keep the source of your site
> proprietary -- is that set in stone?
Definitely not set in stone. As far as the site goes there's not much
Clojure going on there (rails / mysql), and I'd rather keep that part
closed for now so I can concentrate on moving from alpha to beta,
adding features, and fixing bugs. The analyzer, which pulls
metadata / source from libraries, and inserts it into the database is
a different story. Other than the fact that it's extremely hackish,
nothing's really stopping me from EPLing it in the near future.
You also mentioned an API / export process, which I think is a great
idea. This would allow examples to be easily exported to prevent
vendor lock-in.
-Zack
On Jul 9, 12:44 pm, Justin Kramer <jkkra...@gmail.com> wrote:
> I've told Zack that he is free to pull any examples from the wiki for
> use on his site.
> I don't know about collaboration beyond that. The wiki is open source
> and written in Clojure; anyone is free to contribute/fork. At least
> one person has expressed interest in making code contributions.
> Zack, you had mentioned you planned to keep the source of your site
> proprietary -- is that set in stone?
> Justin
> On Jul 9, 12:21 pm, David Nolen <dnolen.li...@gmail.com> wrote:
> > On Fri, Jul 9, 2010 at 4:32 AM, zkim <zachary....@gmail.com> wrote:
> > > Questions / thoughts?
> > > -Zack
> > This is great. I think the main thing is not duplicating effort. This and
> > clojure-examples.appspot.com should really join forces.
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
> 2. Search for a var across the whole ecosystem or in a specific
> library.
> 3. Per var wiki-style examples section.
> 4. Per var comments section.
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> below the source section.
> I'm treating this as an alpha, and I'd really like feedback as to:
> a. How useful this would be to the community.
> b. Specific likes / dislikes about this alpha release.
> c. Feature requests.
> I've set up a feedback mechanism directly through the site (User
> Voice), which allows voting on specific posts. I'm also considering
> setting up a google group for general discussion. Feel free to
> contact me directly through email.
I kind of went back and forth on this. Originally I only parsed out
public vars, but in a couple of instances I found that when tracing
through some code I would hit on private vars.
Perhaps a solution where private vars are hidden from normal flow
(browsing and searching) unless explicitly included by the user?
-Zack
On Jul 9, 2:06 pm, Tom Faulhaber <tomfaulha...@gmail.com> wrote:
> Quick thought: You probably don't want to include private vars.
> On Jul 9, 1:32 am, zkim <zachary....@gmail.com> wrote:
> > Hi All,
> > I'll try to keep this short.
> > I've gotten a lot out of Clojure: I can honestly say that learning
> > this language, and being part of this community has made me a better,
> > happier developer, and I wanted to give something back.
> > One of the pain points that I encountered when learning the language
> > was a lack of examples specific to the individual functions I was
> > trying to wrap my head around at any given time. So I took a whack at
> > the problem, and came up withhttp://clojuredocs.org. It's a site
> > that (I'm hoping) will fill this need by providing a centralized
> > examples database, along with solid search capabilities across both
> > core and third party libraries (core being the focus).
> > Implementation:
> > ClojureDocs.org is a rails site backed by MySQL, along with some
> > clojure code to pull the namespaces / metadata / source and dump them
> > into the database.
> > Highlights:
> > 1. Documentation and source for Clojure core, contrib, and a few third
> > party libraries (random selection out of what I'm personally familiar
> > with, and whatever was on the github trends page that day).
> > 2. Search for a var across the whole ecosystem or in a specific
> > library.
> > 3. Per var wiki-style examples section.
> > 4. Per var comments section.
> > 5. Per var vars-in-this-var and this-var-used-in section (my personal
> > favorite). Looking for a real-world example of a specific function?
> > This is for you. For example,http://clojuredocs.org/v/1978, just
> > below the source section.
> > Lowlights:
> > 1. Ugly URLs! There's a problem in the way that URLs with encoded
> > question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojure.... I've got an email out to the Phusion
> > Passenger mailing list (http://groups.google.com/group/phusion- > > passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any
> > experience in this area drop me a line.
> > I'm treating this as an alpha, and I'd really like feedback as to:
> > a. How useful this would be to the community.
> > b. Specific likes / dislikes about this alpha release.
> > c. Feature requests.
> > I've set up a feedback mechanism directly through the site (User
> > Voice), which allows voting on specific posts. I'm also considering
> > setting up a google group for general discussion. Feel free to
> > contact me directly through email.
I'm sure something like it could be made for ClojureDocs.org once the
API is in place.
General comments on ClojureDocs.org: I think an important aspect of a
collaborative tool like this is quality control. There needs to be
people watching recent updates, making sure examples meet certain
standards (formatted correctly, idiomatic, etc.). To that end, a
complete list of recent updates (with diffs) to go along with the
short list on the homepage would be really nice.
Having a category-based outlines would also be nice. I have one here
for clojure.core, adapted from the Cheatsheet:
> I've actually been thinking about this exact same kind of site for a
> while now and I'm thrilled that I was too lazy to do it so that you
> could do it instead. :)
> One idea that I have that I think would be killer would be to provide
> an API to look up one your examples at the repl so I could do
> something like:
> There are of course many variants of some functions and different
> forms of use, so dealing with the best way to provide useful help
> without an overwhelming number of examples is tricky in the repl, but
> I think worth doing. Along with doc and source, I think example would
> be a killer addition to allowing you to explore the libraries from the
> comfort of your repl.
> Alex
> On Jul 9, 3:32 am, zkim <zachary....@gmail.com> wrote:
> > Hi All,
> > I'll try to keep this short.
> > I've gotten a lot out of Clojure: I can honestly say that learning
> > this language, and being part of this community has made me a better,
> > happier developer, and I wanted to give something back.
> > One of the pain points that I encountered when learning the language
> > was a lack of examples specific to the individual functions I was
> > trying to wrap my head around at any given time. So I took a whack at
> > the problem, and came up withhttp://clojuredocs.org. It's a site
> > that (I'm hoping) will fill this need by providing a centralized
> > examples database, along with solid search capabilities across both
> > core and third party libraries (core being the focus).
> > Implementation:
> > ClojureDocs.org is a rails site backed by MySQL, along with some
> > clojure code to pull the namespaces / metadata / source and dump them
> > into the database.
> > Highlights:
> > 1. Documentation and source for Clojure core, contrib, and a few third
> > party libraries (random selection out of what I'm personally familiar
> > with, and whatever was on the github trends page that day).
> > 2. Search for a var across the whole ecosystem or in a specific
> > library.
> > 3. Per var wiki-style examples section.
> > 4. Per var comments section.
> > 5. Per var vars-in-this-var and this-var-used-in section (my personal
> > favorite). Looking for a real-world example of a specific function?
> > This is for you. For example,http://clojuredocs.org/v/1978, just
> > below the source section.
> > Lowlights:
> > 1. Ugly URLs! There's a problem in the way that URLs with encoded
> > question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojure.... I've got an email out to the Phusion
> > Passenger mailing list (http://groups.google.com/group/phusion- > > passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any
> > experience in this area drop me a line.
> > I'm treating this as an alpha, and I'd really like feedback as to:
> > a. How useful this would be to the community.
> > b. Specific likes / dislikes about this alpha release.
> > c. Feature requests.
> > I've set up a feedback mechanism directly through the site (User
> > Voice), which allows voting on specific posts. I'm also considering
> > setting up a google group for general discussion. Feel free to
> > contact me directly through email.
*argh*. well at least my email is now finally on the whitelist.
What do you guys think of some of the ideas presented in the "Solving Clojure's Documentation Problem Without Fragmentation" thread? (Which I sent shortly after this thread started, but ended up being posted several hours later).
P.S. clojuredoc.org might be irrelevant if you guys choose to collaborate on the same project, but what do you think about using Justin's codebase, or an Aleph-based server to host the thing instead of Ruby/Rails? (see the link above for more details)
> I'm sure something like it could be made for ClojureDocs.org once the > API is in place.
> General comments on ClojureDocs.org: I think an important aspect of a > collaborative tool like this is quality control. There needs to be > people watching recent updates, making sure examples meet certain > standards (formatted correctly, idiomatic, etc.). To that end, a > complete list of recent updates (with diffs) to go along with the > short list on the homepage would be really nice.
> Having a category-based outlines would also be nice. I have one here > for clojure.core, adapted from the Cheatsheet:
> FYI, I'll probably be implementing a mass export feature for the wiki, > so you could write a script or something to automate an import.
> Awesome work, Zack.
> Justin
> On Jul 9, 2:25 pm, Alex Miller <alexdmil...@yahoo.com> wrote: >> I've actually been thinking about this exact same kind of site for a >> while now and I'm thrilled that I was too lazy to do it so that you >> could do it instead. :)
>> One idea that I have that I think would be killer would be to provide >> an API to look up one your examples at the repl so I could do >> something like:
>> There are of course many variants of some functions and different >> forms of use, so dealing with the best way to provide useful help >> without an overwhelming number of examples is tricky in the repl, but >> I think worth doing. Along with doc and source, I think example would >> be a killer addition to allowing you to explore the libraries from the >> comfort of your repl.
>> Alex
>> On Jul 9, 3:32 am, zkim <zachary....@gmail.com> wrote:
>>> Hi All,
>>> I'll try to keep this short.
>>> I've gotten a lot out of Clojure: I can honestly say that learning >>> this language, and being part of this community has made me a better, >>> happier developer, and I wanted to give something back.
>>> One of the pain points that I encountered when learning the language >>> was a lack of examples specific to the individual functions I was >>> trying to wrap my head around at any given time. So I took a whack at >>> the problem, and came up withhttp://clojuredocs.org. It's a site >>> that (I'm hoping) will fill this need by providing a centralized >>> examples database, along with solid search capabilities across both >>> core and third party libraries (core being the focus).
>>> Implementation: >>> ClojureDocs.org is a rails site backed by MySQL, along with some >>> clojure code to pull the namespaces / metadata / source and dump them >>> into the database.
>>> Highlights: >>> 1. Documentation and source for Clojure core, contrib, and a few third >>> party libraries (random selection out of what I'm personally familiar >>> with, and whatever was on the github trends page that day).
>>> 2. Search for a var across the whole ecosystem or in a specific >>> library.
>>> 3. Per var wiki-style examples section.
>>> 4. Per var comments section.
>>> 5. Per var vars-in-this-var and this-var-used-in section (my personal >>> favorite). Looking for a real-world example of a specific function? >>> This is for you. For example,http://clojuredocs.org/v/1978, just >>> below the source section.
>>> Lowlights: >>> 1. Ugly URLs! There's a problem in the way that URLs with encoded >>> question marks are being handled, so I had to move fromhttp://clojuredocs.org/clj-ssh/clj-ssh.core/file-pathtohttp://clojure.... I've got an email out to the Phusion >>> Passenger mailing list (http://groups.google.com/group/phusion- >>> passenger/browse_thread/thread/ed2eadfdac5c166f) but if you've got any >>> experience in this area drop me a line.
>>> I'm treating this as an alpha, and I'd really like feedback as to: >>> a. How useful this would be to the community. >>> b. Specific likes / dislikes about this alpha release. >>> c. Feature requests.
>>> I've set up a feedback mechanism directly through the site (User >>> Voice), which allows voting on specific posts. I'm also considering >>> setting up a google group for general discussion. Feel free to >>> contact me directly through email.
>>> Questions / thoughts?
>>> -Zack
> -- > 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+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
> I kind of went back and forth on this. Originally I only parsed out > public vars, but in a couple of instances I found that when tracing > through some code I would hit on private vars.
I'm suspicious of showing source code to the reader with everything more than a small quite nondescript link. The contract is the docstring. Looking at the code might be interesting but non-helpful. You start relying on implementation details, while these might change at any time (eg. introduction of transients, etc.). I would *not* show the source code and I would *not* document private vars. They are not part of the contract and should not show up in public API documentation.
Hi Zack, first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
1) http://github.com/defn/walton - have a look at it, it might be a good way to fetch examples for functions where none are provided yet.
2) Will it be possible to put other 3rd party libs on there - since I'd like to add some of mine, it's likely better to have them documented centrally then keeping a own documentation for each library. :)
> Hi Zack,
> first of all, great effort there :) having a place for clojure docs is awesome. Two things come to mind:
> 1)http://github.com/defn/walton- have a look at it, it might be a good way to fetch examples for functions where none are provided yet.
> 2) Will it be possible to put other 3rd party libs on there - since I'd like to add some of mine, it's likely better to have them documented centrally then keeping a own documentation for each library. :)
> I've gotten a lot out of Clojure: I can honestly say that learning
> this language, and being part of this community has made me a better,
> happier developer, and I wanted to give something back.
> One of the pain points that I encountered when learning the language
> was a lack of examples specific to the individual functions I was
> trying to wrap my head around at any given time. So I took a whack at
> the problem, and came up withhttp://clojuredocs.org. It's a site
> that (I'm hoping) will fill this need by providing a centralized
> examples database, along with solid search capabilities across both
> core and third party libraries (core being the focus).
> Implementation:
> ClojureDocs.org is a rails site backed by MySQL, along with some
> clojure code to pull the namespaces / metadata / source and dump them
> into the database.
> Highlights:
> 1. Documentation and source for Clojure core, contrib, and a few third
> party libraries (random selection out of what I'm personally familiar
> with, and whatever was on the github trends page that day).
> 2. Search for a var across the whole ecosystem or in a specific
> library.
> 3. Per var wiki-style examples section.
> 4. Per var comments section.
> 5. Per var vars-in-this-var and this-var-used-in section (my personal
> favorite). Looking for a real-world example of a specific function?
> This is for you. For example,http://clojuredocs.org/v/1978, just
> below the source section.
> I'm treating this as an alpha, and I'd really like feedback as to:
> a. How useful this would be to the community.
> b. Specific likes / dislikes about this alpha release.
> c. Feature requests.
> I've set up a feedback mechanism directly through the site (User
> Voice), which allows voting on specific posts. I'm also considering
> setting up a google group for general discussion. Feel free to
> contact me directly through email.
Very cool. Let me start by saying thanks to everyone who has been involved in the various threads on improving documentation, especially those who, like Zack, have taken substantial action.
Here are a bunch of ideas, in no particular order:
(1) Ease of contribution is huge, and http://clojuredocs.org looks good on this front. Stick to it.
(2) +1 on hiding private APIs. We use private APIs carefully and deliberately in Clojure, and I would hate to facilitate people writing code that will break later.
(3) +1 on making it very easy to see which version of an API you are looking at. This should be both at the top level (some way to say "show me 1.1") and on a per-var basis, reading the :added metadata.
(4) Provenance matters. Clojure itself is very careful to have people sign a CA before contributing code. The bar may be somewhat different for a documentation site, but it still needs to be carefully considered.
(5) Continuity matters. We have already had some pain with useful resources popping up on the web and then having the maintainer go AWOL with no succession plan. There are several steps any documentation site should take to address this: (a) open sourcing everything (b) including multiple committers and admins on the site itself and (c) providing an easy API to suck the data out.
(6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site.
(7) Quality matters. There are multiple possible ways to make sure that the cream rises: letting people up and downvote, making it easy for "editors" to track new submissions, etc.
> I've gotten a lot out of Clojure: I can honestly say that learning > this language, and being part of this community has made me a better, > happier developer, and I wanted to give something back.
> One of the pain points that I encountered when learning the language > was a lack of examples specific to the individual functions I was > trying to wrap my head around at any given time. So I took a whack at > the problem, and came up with http://clojuredocs.org. It's a site > that (I'm hoping) will fill this need by providing a centralized > examples database, along with solid search capabilities across both > core and third party libraries (core being the focus).
> Implementation: > ClojureDocs.org is a rails site backed by MySQL, along with some > clojure code to pull the namespaces / metadata / source and dump them > into the database.
> Highlights: > 1. Documentation and source for Clojure core, contrib, and a few third > party libraries (random selection out of what I'm personally familiar > with, and whatever was on the github trends page that day).
> 2. Search for a var across the whole ecosystem or in a specific > library.
> 3. Per var wiki-style examples section.
> 4. Per var comments section.
> 5. Per var vars-in-this-var and this-var-used-in section (my personal > favorite). Looking for a real-world example of a specific function? > This is for you. For example, http://clojuredocs.org/v/1978, just > below the source section.
> I'm treating this as an alpha, and I'd really like feedback as to: > a. How useful this would be to the community. > b. Specific likes / dislikes about this alpha release. > c. Feature requests.
> I've set up a feedback mechanism directly through the site (User > Voice), which allows voting on specific posts. I'm also considering > setting up a google group for general discussion. Feel free to > contact me directly through email.
> Questions / thoughts?
> -Zack
> -- > 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+unsubscribe@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en
On 10 July 2010 15:06, Stuart Halloway <stuart.hallo...@gmail.com> wrote:
> (6) Because docstrings are designed for consumption at a REPL, they may in some cases presume a fixed font. Worth considering for display on the site.
What about giving function documentation the same "wiki" behaviour that the examples have? Start off with the docstrings as the initial values, but allow people to update them. The web allows longer and better formatted documentation than a standard Clojure docstring (which needs to fit in a terminal).
