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:
## 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:
(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.