I assume most people here would agree with this: "Nothing is merely a pull request; it is someone's valuable time spent in contemplation and action."
At the same time, I assume most people who would use Clojure will also know something about Git, and I think this applies even to fairly new programmers (though not total beginners, and, as I said before, if the question is "How do we make Clojure as easy as PHP?" I think it is an interesting challenge, and one we are far from having an answer for). I am uncertain what restrictions might be appropriate for a documentation site. As you say: "I hear PHP suffered from misleading and messy community docs… though it was very useful for my (basic) purposes." I suppose a good answer would combine the openness of a wiki with some kind of voting so that visitors could see which edits were judged to be the best -- something like StackOverflow. Failing that, we could point people to the pull requests on Github, and tell them that there is important information in the pull requests, which might sound messy, but I don't think it would be any more messy that the messy community docs that you say PHP had. --- lawrence On Thursday, May 7, 2015 at 5:48:11 AM UTC-4, Tj Gabbour wrote: > > First of all, I apologize to the group for any unfriendliness in my > response. (Which may be poisonous to this group’s culture, I don’t know. > Unfortunately, many old frustrations of mine were triggered, when I felt my > question was given an uncharitable interpretation.) > > The term “pull request” hides a lot of complexity. (Some point out > <https://modelviewculture.com/pieces/what-your-open-source-culture-really-says-part-one> > > it means “Go fuck yourself.”) Nothing is merely a pull request; it is > someone's valuable time spent in contemplation and action. > > If we were in a team, here’s some things we might discuss: > > - How to support each other? (Given varying > skills/confidence/energy/power.) > - What is our ultimate goal? (“Documentation” almost never is one. > It’s just a tactic.) > - What is our audience? (Why do we wish to serve them, and how?) > - What is our process for improving quality/effectiveness? > (After-action reviews, building institutional knowledge…) > - Who are external partners, and how do they think? (We’ve mentioned > Clojurewerkz and The Clojure.org 14.) > > > So when we’re evaluating contributing to clojure-docs.org: > > - Should we add metrics to show us how many people read > clojure-docs.org, as a first step to gauging effectiveness? > - What do you think about the content there, and how would you make it > far better? (Pictures? Examples? Literary structure?) > > > When we’re evaluating contributing to clojure.org: > > - Examples of our intended audience, and what problems do they have? > - How to best work with the strengths of The Clojure.org 14’s > conservativism? > - Clojure’s uses are diverse; how do we represent its core? Might it > be entirely appropriate to have a sparse site, more or less like it is > now? > Because the real entry-points should be around emerging clusters like > React.js libs? > > > These may seem like lots of things to think about, but so is writing 100 > good lines of debugged code. > > *are any restrictions that should be put on a documentation site?* >> >> > Yes, depending on what you want to avoid. > > For example, I hear PHP suffered from misleading and messy community docs… > though it was very useful for my (basic) purposes. > > But once we agree there need to be restrictions, what can we do to > mitigate the downsides? For example, raising barriers to entry can lead to > intimidation. But you can mitigate it by being supportive and offering > mentoring. Or simply being proactively honest and apologetic about it. > > I hope I didn't misunderstand your points? > -- 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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
