Quick question: would it be possible to copy stuff from dev.clojure.org? I wrote some stuff over there, under the CA agreement, but it's kind of a wiki format so it might be unclear who 'owns' it.
BTW, I noticed the front page of clojure.org got its headings cleaned up----thank you to whoever did that! Really looks great. On Oct 8, 9:26 am, Michael Klishin <michael.s.klis...@gmail.com> wrote: > ## 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 athttp://clojure-doc.organd > 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/michaelklishinhttp://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
