I'm very excited about this. As has been said before, all skills aren't located in the same person, and someone with ability to develop does not necessarily have the competence, the guts, or the time to write great end user documentation.
So I'm "high five" for this project, especially because documentation at different abstraction levels requires not / needs not be made by the same person / people. But to me, there's a remaining "pain point". clojure.org is to be seen as the "reference documentation". It's like a normalized database for experts, the "man page" for Clojure. So when things change in clojure.org, portions of the clojure-doc site will eventually have to be adapted. What clojure/dev could do (if it's not already possible) is make deltas of changes made to clojure.org ridiculously easy to track from the outside. If clojure.org were already on github, for instance, it would be super easy for someone to fork it, add a tag to the last commit marking a "updated up to this revision of the site" checkpoint, etc. Of course, this applies as well to other tools/libraries that will be covered by other documentation (yes, I'm looking at me with Counterclockwise also ;) ). 2012/10/8 Michael Klishin <michael.s.klis...@gmail.com> > ## Announcing clojure-doc.org > > I am starting a new thread because the existing one about CDS is now > polluted by all kinds of off-topics. > > About a week ago, John Gabrielle announced CDS (Clojure Documentation > Site): a new Clojure documentation resource > for the Clojure community by the Clojure community. > > We are past dealing with all the plumbing and happy to announce that our > work is now public at http://clojure-doc.org and > you are welcome join the effort: we tried to make it as easy as possible. > > > ## How It Works > > We have a repository on GitHub [1] that has Markdown files, toolchain > setup instructions and several article > stubs. The stubs help contributors pick a topic to write about and not > worry too much about how to structure the document. > They are training wheels for documentation writing, if you will. > > To contribute, for the repository [1], create a topic branch, make your > changes and submit a pull request on GitHub. No > contributor agreement process, no JIRA, no patches. Then an existing > contributor will either merge your pull request or > suggest changes. > > The toolchain currently requires Ruby *and* Python (for code > highlighting). We decided that it's good enough for now. > There are instructions about setting everything up in the README. > > There is no separate mailing list, so if you want to ask or suggest > something, do it here. > > > ## What We Have So Far > > Given that CDS is literally a few days old (after we migrated to the new > toolchain and got to actual content), there is not > much to show but a few tutorials and guides should give you an idea of > what we want it to look like: > > * http://clojure-doc.org/articles/tutorials/getting_started.html > * http://clojure-doc.org/articles/tutorials/introduction.html > * http://clojure-doc.org/articles/language/functions.html > * http://clojure-doc.org/articles/ecosystem/community.html > * http://clojure-doc.org/articles/ecosystem/libraries_directory.html > > > ## What CDS Covers > > CDS' goal is to cover more than just the language. It is certainly > cruicially important to have good tutorials and comprehensive > guides on Clojure. But when using Clojure in real world projects, you will > need to know about the JVM ecosystem, Leiningen, > how to write tests, what libraries are out there, how to profile code, JVM > tooling for ops, how to develop and distribute libraires, > and much more. > > So there is group of articles about "the Ecosystem stuff": think > Leiningen, popular libraries or how to use VisualVM to find > hot spots and investigate concurrency hazards in your apps. > > This means that if you feel that documenting sequences is boring but > excited about the ops side of software engineering, you > can still contribute to CDS and enjoy the process. > > When documenting various tools, sometimes it makes more sense to just > link to existing documentation, which is what we > do for Leiningen. > > > ## Low-hanging Fruits > > There are currently several articles that already have their structure in > place, what is left is writing the content and code > examples. For example, you don't have to be a genius or a Clojure expert > to write articles such as > > * Books > * Java interop > * Collections and Sequences > * Namespaces (ok, you *have* to be a genius to explain the ns macro well > but some people certainly can do that) > > If you want to start working on one of those articles or have existing > content you've authored that can be ported, > please let us know. > > Topics like Concurrency & Parallelism and Laziness will take more effort, > this is why we did not bother with writing any > initial structure for their articles. > > > ## Call to Arms > > If your company uses Clojure or has interest in adopting it and has "open > source Fridays", "hacker time" or something > similar, consider contributing to CDS. This will literally benefit the > entire Clojure community, all the current and future users. > > Not only every single Clojure user benefits from better documentation, it > also gets outdated way slower than that hot new open source > library you wanted to tinker with. In other words, it's one of the best > ways to invest of your OSS time budget (if you ask me). > > No contribution is too small: feel free to suggest grammar improvements, > better code examples, submit pull requests with just > one new paragraph or even a couple of spelling corrections. Editing and > proof-reading is also a great way to contribute. > > If you have design and/or frontend development skills, you are more than > welcome to make CDS more legible, easy to navigate, > and simply better looking. > > If you need examples of what's possible, here's what 2 people could > produce in about 6 months in their spare time: > > * Monger documentation: http://clojuremongodb.info > * Neocons documentation: http://clojurneo4j.info > * Welle documentation: http://clojurriak.info > * Elastisch documentation: http://clojureelasticsearch.info > * Langohr documentation: http://clojurerabbitmq.info > * Quartzite documentation: http://clojurequartz.info > > (and no, I am not trying to market my projects here). You know what's even > better? Both of those > 2 people are not native English speakers. Imagine what would be possible > if CDS gets 10-15 regular contributors and > maybe 10 more people proof-reading stuff. > > > ## What You Must Not Do > > * Do not copy content from clojure.org (covered by the existing CA > process, the thing we are trying to avoid) > * Do not copy content from existing books > * Do not copy content from blog posts unless you are the author > > > ## What CDS is Not > > CDS does not try to cover API reference. clojuredocs.org does that pretty > well already. > > > ## Questions > > If you have any questions or ideas, we will be happy to answer them here. > > > 1. http://github.com/clojuredocs/cds > -- > MK > > http://github.com/michaelklishin > http://twitter.com/michaelklishin > > -- > 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
