One way to think about documentation is this: you've just written this great and useful library! You surely want it to be useful and people to actually use it, right? (See earlier in the thread about Pedestal.) Well, the only way you'll reach that goal is by having solid documentation that can provide an on-ramp to people who you think should be using the library, but don't know anything about it.
We all know what bad documentation looks like, but what about good documentation? Examples would be useful here. Two projects whose documentation I like: * core.match * Immutant -- Morgon 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.
