I'm pretty sure you have already thought about it and it's me that missed your considerations, but why we are not using a wiki-based tool, like Wordpress, instead of forking a git branch?
On Mon, Oct 8, 2012 at 6:25 PM, 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 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
