ANN clojure-doc.org (aka CDS), a new community-driven Clojure documentation site

768 views
Skip to first unread message

Michael Klishin

unread,
Oct 8, 2012, 12:25:35 PM10/8/12
to clo...@googlegroups.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:



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


--
MK

http://github.com/michaelklishin
http://twitter.com/michaelklishin

nchurch

unread,
Oct 8, 2012, 1:42:59 PM10/8/12
to Clojure
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:
>  *http://clojure-doc.org/articles/ecosystem/libraries_directory.html

John Gabriele

unread,
Oct 8, 2012, 1:50:02 PM10/8/12
to clo...@googlegroups.com
On Monday, October 8, 2012 12:26:23 PM UTC-4, Michael Klishin 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

Just one ell. :)
 
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


The site is now generated using jekyll, and uses pygments for syntax highlighting (rather than using Pandoc and my own tools like I originally had it).

But there's one minor issue we're not crazy about: for code blocks to get syntax highlighting, they must now be written `{% highlight clojure %} ... {% endhighlighting %}` instead of

   ```clojure ... ```

If you know how to set things up such that we can use the regular backtick syntax for codeblocks with jekyll, please let us know.

Thanks,
---John

Laurent PETIT

unread,
Oct 8, 2012, 3:19:12 PM10/8/12
to clo...@googlegroups.com
2012/10/8 nchurch <nchu...@gmail.com>
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.

By signing the CA agreement you did not give away your copyright on stuff you made, so I think it's ok for you to copy what *you* wrote there.
 

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@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+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en

Michael Klishin

unread,
Oct 8, 2012, 3:25:32 PM10/8/12
to clo...@googlegroups.com
2012/10/8 Laurent PETIT <lauren...@gmail.com>

By signing the CA agreement you did not give away your copyright on stuff you made, so I think it's ok for you to copy what *you* wrote there.

This is my understanding as well but I am not a lawyer.

Content from clojure.org won't be merged for two reasons:

 * I don't want CDS to be ruined by or end up being affiliated with the existing process in any way.
 * CDS caters to newcomers and "somewhat experienced" developers, not experts. clojure.org content in my opinion was and still is very expert-oriented.

So lets just not use any of the clojure.org or dev.clojure.org content. It is much more important to get new contributors on board
and keep CDS going than to save 30 minutes of time by copying something here and there.

Dave Della Costa

unread,
Oct 8, 2012, 11:28:05 PM10/8/12
to clo...@googlegroups.com
Hi John, regarding the backticks for code blocks, are you talking about
using Markdown?

It looks like because Jekyll uses the markdown parser Maruku
(http://maruku.rubyforge.org/maruku.html), instead of the redcarpet that
GFM uses, you'll have to use tildes instead of backticks.

Dave

(12/10/09 2:50), John Gabriele wrote:
> On Monday, October 8, 2012 12:26:23 PM UTC-4, Michael Klishin wrote:
>
> ## Announcing clojure-doc.org <http://clojure-doc.org>

Brent Millare

unread,
Oct 9, 2012, 12:23:37 PM10/9/12
to clo...@googlegroups.com
As a start for my contributions, I want to open up some topics for discussion.


1. Front Page Design

Currently, it looks like the front page has a bunch of miniature slides. Do we want the front page to mainly be the focus of advertisement and have a separate navigation system (aka "see all contents")? Or do we want navigation to be the front page. In this case, we'll need to create some sort of high level tree structure.

2. The advertisement page to me, has two purposes:
  I. Provide motivation for the CDS
  II. Provide motivation for using clojure itself

These are separate but important concerns. How should we prioritize these?

We can also talk about adding visuals like abstract pictures that go along with the content.

3. Styling Design

I noticed the site changes the style depending on the width, which is a cool feature. But I don't like the line breaking behavior of the medium width. I feel it might look visually better if the font size was reduced to preserve the lines.

Michael Klishin

unread,
Oct 9, 2012, 1:09:59 PM10/9/12
to clo...@googlegroups.com
2012/10/9 Brent Millare <brent....@gmail.com>
1. Front Page Design

Currently, it looks like the front page has a bunch of miniature slides. Do we want the front page to mainly be the focus of advertisement and have a separate navigation system (aka "see all contents")? Or do we want navigation to be the front page. In this case, we'll need to create some sort of high level tree structure.

Flat navigation (a list of styles) is known to work well for docs. Wikis and "high level trees" eventually
turn into something that is very hard to navigate. One extra click may make a different for an online
store but for an OSS project documentation site it's OK to have it.

That said, we are open to hearing from people who are actual interaction designers.
 

2. The advertisement page to me, has two purposes:
  I. Provide motivation for the CDS
  II. Provide motivation for using clojure itself

These are separate but important concerns. How should we prioritize these?


I over II. II should be covered by clojure.org.
 
We can also talk about adding visuals like abstract pictures that go along with the content.

3. Styling Design

I noticed the site changes the style depending on the width, which is a cool feature. But I don't like the line breaking behavior of the medium width. I feel it might look visually better if the font size was reduced to preserve the lines.

CDS currently can be read easily on both desktop and tablets. We can change font size or line heights
and see how it goes, as long as things are still readable on smaller screens.

In general, styling *right now* is way less important than adding content.

Michael Klishin

unread,
Oct 9, 2012, 1:17:52 PM10/9/12
to clo...@googlegroups.com
2012/10/9 Michael Klishin <michael....@gmail.com>

Flat navigation (a list of styles)

This should read "a list of articles"

Andrew Brehaut

unread,
Oct 10, 2012, 6:15:00 PM10/10/12
to clo...@googlegroups.com
On Tuesday, October 9, 2012 5:26:23 AM UTC+13, Michael Klishin wrote:
 * Do not copy content from blog posts unless you are the author

I wrote a brief introduction to web development in clojure[1] last year. If anyone wants to use it as part of or a basis for an article about web dev for CDS, please feel free. Anyone doing so will need to update the content to ring 1.1 and clojure 1.4.

Regards,

Andrew Brehaut

Roberto Mannai

unread,
Oct 10, 2012, 6:38:21 PM10/10/12
to clo...@googlegroups.com
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?

John Gabriele

unread,
Oct 10, 2012, 7:07:35 PM10/10/12
to clo...@googlegroups.com

On Wednesday, October 10, 2012 6:38:31 PM UTC-4, robermann79 wrote:
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?


My original goals for CDS were to have it be a sort of organic “sundry bunch of docs” type of project: less formality than “official” documentation, but more boundaries than a wiki (i.e., “don’t go editing other people’s docs with wild abandon”). (I blogged about it at http://www.unexpected-vortices.com/blog/2012/clojure-docs-and-cds.html ). I went with md docs at github because:

  * most contributors would probably already be familiar with github,
  * it's easy to write markdown docs,
  * github allows users to click the "edit" button and edit right there in browser (it takes care of forking and helping you send the pull-request),
  * I wanted there to be an easily viewable "paper trail" of changes, and
  * you can view markdown pages right at github,

Really, that 3rd bullet point is key: since you can just cilck the edit button and edit right there, contributors don't even need to know anything about git to contribute. They just need to have an account at github. It becomes basically the same as editing a wiki. :)

Once Michael and others joined in, the goals changed just a bit. Now, CDS is more aimed at being high-quality technical docs with little duplication which are suitable for display at some future doc.clojure.org site area. But keeping a collection of markdown docs at github is still currently the best way to accomplish this, I think.

---John

Michael Klishin

unread,
Oct 10, 2012, 7:16:23 PM10/10/12
to clo...@googlegroups.com
robermann79:

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?

 
 * Developers prefer writing docs and code examples in their favorite editor and not a browser input field
 * Rapid feedback when writing and working on code examples locally in the REPL
 * Everybody and their grandma are on GitHub. Asking people to sign up for a yet another wiki-like system? Please.
 * Static HTML is as low maintenance as it gets when it comes to hosting content
 * Full control over how we want the site to be structured and what we want it to look like

there are more reasons but I hope this answers your question.

MK

Laurent PETIT

unread,
Oct 11, 2012, 5:35:57 AM10/11/12
to clo...@googlegroups.com
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....@gmail.com>

Michael Klishin

unread,
Oct 11, 2012, 10:32:26 AM10/11/12
to clo...@googlegroups.com
2012/10/11 Laurent PETIT <lauren...@gmail.com>

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 keeping clojure.org content in a git repository is not possible, then notify this list.

gaz jones

unread,
Oct 11, 2012, 1:50:44 PM10/11/12
to clo...@googlegroups.com
I have 3 blog posts I wrote to help some colleagues get up to speed
with clojure / emacs:

http://blog.gaz-jones.com/2012/02/01/setting_up_emacs_for_clojure_development.html
http://blog.gaz-jones.com/2012/02/02/clojure_development_cycle.html
http://blog.gaz-jones.com/2012/02/03/clojure_command_line_apps.html

They are all based on Emacs 24, leiningen 1.x, and swank-clojure. Is
there any appetite for me to convert / update them and merge them into
CDS under the tutorials section? I have been told by a few people that
they found them useful and I tried but failed to find anything similar
elsewhere on the interwebs (particularly the clojure development cycle
one).

Gaz

Grant Rettke

unread,
Oct 11, 2012, 2:29:05 PM10/11/12
to clo...@googlegroups.com
On Thu, Oct 11, 2012 at 12:50 PM, gaz jones <gareth....@gmail.com> wrote:
> I have 3 blog posts I wrote to help some colleagues get up to speed
> with clojure / emacs:

Looks great. You never know what is the best thing for everyone, so
what works for you will probably work for others, too.

Michael Klishin

unread,
Oct 11, 2012, 2:37:10 PM10/11/12
to clo...@googlegroups.com
2012/10/11 gaz jones <gareth....@gmail.com>

They are all based on Emacs 24, leiningen 1.x, and swank-clojure. Is
there any appetite for me to convert / update them and merge them into
CDS under the tutorials section? I have been told by a few people that
they found them useful and I tried but failed to find anything similar
elsewhere on the interwebs (particularly the clojure development cycle
one).

Looks like a good basis for a guide on Emacs (and Clojure development cycle). The CLI
app tutorial will need a bit of adaptation but covering tools.cli is very important for CDS.

gaz jones

unread,
Oct 11, 2012, 2:56:04 PM10/11/12
to clo...@googlegroups.com
Alright, I'll convert the appropriate ones and send you a pull request
when I'm done. I'm happy to pick up writing a tools.cli tutorial too
when I get some spare time. Thanks for kickstarting the effort, it's
shaping up to be a great resource.

Murphy McMahon

unread,
Oct 11, 2012, 8:27:02 PM10/11/12
to clo...@googlegroups.com
I'm not really enough of an authority to contribute much at this
point, but I wanted to take a second, as someone who has been learning
Clojure (and Emacs) over the past year or so, to applaud the effort
and share my opinion:

I really like something like this: https://gobyexample.com/

It is oriented around concrete tasks, the information density is
moderate, and the interface presents a somewhat linear path while also
making it easy to jump to a specific topic.

I really get lost with something like this: http://emacswiki.org/

That site is full of excellent information, and granted that Emacs is
an enormous topic with a community to match it, but without Google
there is no way I'd ever get anything from it.

Just food for thought. Thanks everyone.

M
Reply all
Reply to author
Forward
0 new messages