ANN: a Clojure docs site, and github organization

[John Gabriele]

Hi all,

I seem to have found myself writing some Clojure docs again. They are
currently hosted at https://github.com/clojuredocs/cds , and are
*currently* on display at
http://www.unexpected-vortices.com/clojure/cds/index.html . Though,
there are plans in the works to render the docs using the same tools
as the Clojurewerks.org docs, rather than my own little
[rippledoc](https://github.com/uvtc/rippledoc) tool that's currently
being used.

The docs are just regular markdown files.

Please see the [Readme](https://github.com/clojuredocs/cds#readme) for
more info, but the main idea is to have a community repository of
Clojure docs. If you can write well, and want to add a doc you've
written, send a pull-request. :)

Note that the repository lives under the new "clojuredocs"
organization, and not my own username (uvtc). It's certainly intended
to be a community-driven project.

I've already written a few docs (see the ToC), and there are others
who are collaborators but who have not added their docs yet.

---John

[Paul deGrandis]

This is great to see.  Along side efforts like Fogus' REPL love - http://readevalprintlove.fogus.me/ - we're well on our way fixing the documentation problems in our community.
I could definitely see something like this migrating into docs.clojure.org once it reached maturity.

Huge thanks to everyone involved in these efforts and responding the call to action.

Also, thanks to Andy Fingerhut - who patched up the docs on contributing and helped to improve the ticket triage process.
And thanks to Stu Halloway for taking some time off list to sort out some issues and help push some things forward.

Paul // ohpauleez

[Laurent PETIT]

2012/10/4 Paul deGrandis <paul.de...@gmail.com>

This is great to see.  Along side efforts like Fogus' REPL love - http://readevalprintlove.fogus.me/ - we're well on our way fixing the documentation problems in our community.
I could definitely see something like this migrating into docs.clojure.org once it reached maturity.

Huge thanks to everyone involved in these efforts and responding the call to action.

Sorry, I couldn't resist the temptation to remind you of this: http://www.ted.com/talks/derek_sivers_keep_your_goals_to_yourself.html

Cheers,

-- 

Laurent

 

Also, thanks to Andy Fingerhut - who patched up the docs on contributing and helped to improve the ticket triage process.
And thanks to Stu Halloway for taking some time off list to sort out some issues and help push some things forward.

Paul // ohpauleez

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

[Bronsa]

Starting two different projects at the same time with almost the same purpose seems a waste of efforts...
Wouldn't it be better for readevalprintlove and clojuredocs to join forces from the beginning?

2012/10/4 Laurent PETIT <lauren...@gmail.com>

[Michael Klishin]

2012/10/5 Bronsa <brob...@gmail.com>

Wouldn't it be better for readevalprintlove and clojuredocs to join forces from the beginning?

It's not clear what readevalprintlove wants to be. clojuredocs has been discussed for a while by some people who care

about Clojure documentation. There are pretty specific plans about the guides and moving clojuredocs.org forward

to 1.4 and (hopefully, at some point) multi-version support. In part the guides portion of clojuredocs (the organization)

will follow the clojurewerkz.org projects model which is known to work well and even produced some tools

we can easily reuse and adapt.

readevalprintlove looks like a fancy playground so far.

There are multiple aspects to good documentation, see http://jacobian.org/writing/great-documentation/

--
MK

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

[Wes Freeman]

I think the goals are sufficiently different.

[Paul deGrandis]

Sorry, I couldn't resist the temptation to remind you of this: http://www.ted.com/talks/derek_sivers_keep_your_goals_to_yourself.html

 DOh! (and this is one of my favorite TED talks!)
Indeed, I didn't mean to state what was going to done before it was done - just that I was happy to see people pick up the torch.

Regarding REPL Love -
I think the two projects are indeed sufficiently different and I think they complement each other quite well.  It actually excites me to see both projects happening right now.  It speaks to the character of the individuals that make up this community.

Paul

[Michael Fogus]

> readevalprintlove looks like a fancy playground so far.

You say that as if it's a bad thing. I'm of the opinion that these
kinds of efforts should have a low barrier to contribution and be fun.
It's difficult to motivate people to perform a thankless task, so it
should seem like play as much as possible along the way.

[Michael Fogus]

> Starting two different projects at the same time with almost the same
> purpose seems a waste of efforts...
> Wouldn't it be better for readevalprintlove and clojuredocs to join forces
> from the beginning?

All information should be freely available, so the sharing aspect is
present from the start. As for wasted effort I would say that any
effort in this direction is a plus, but your point is valid. We're all
friends right? It'll work out for the best for Clojure I'm sure.

[David Nolen]

+1 

[Grant Rettke]

My co-workers and I were debating this at work the other day. My
worldview is that it takes hard work to learn good things, but at the
same time it can be fun and even brief. Kent Dybvig's _The Scheme
Programming Language_ is a superb example. The other four developers
said that I'm the 20% and that approach is too pedagogical, that you
need to make everything constant entertainment. _Practical Common
Lisp_ was cited as an example.

I'm just glad there are options.

I'm still looking for Clojure materials that go to this level of detail:

http://docs.racket-lang.org/reference/eval-model.html#(part._module-phase)

Since Clojure is all compiled immediately I assume it doesn't have
phases other than macros compile first.

[Michael Klishin]

2012/10/5 Michael Fogus <mef...@gmail.com>

You say that as if it's a bad thing.  I'm of the opinion that these
kinds of efforts should have a low barrier to contribution and be fun.

My apologies, I did not imply that it is a bad thing, only that it is not entirely clear what direction the project

will take. While for CDS it is pretty clear (at least to people who have started it).

While we are at this fun stuff, can we also make the CA submission process fun?

[Mayank Jain]

On Fri, Oct 5, 2012 at 6:54 PM, Michael Klishin <michael....@gmail.com> wrote:

2012/10/5 Michael Fogus <mef...@gmail.com>

You say that as if it's a bad thing.  I'm of the opinion that these
kinds of efforts should have a low barrier to contribution and be fun.

My apologies, I did not imply that it is a bad thing, only that it is not entirely clear what direction the project

will take. While for CDS it is pretty clear (at least to people who have started it).

While we are at this fun stuff, can we also make the CA submission process fun?

+1

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

--
Regards,
Mayank.

[Andy Fingerhut]

On Oct 4, 2012, at 1:34 PM, Michael Klishin wrote:

There are pretty specific plans about the guides and moving clojuredocs.org forward

to 1.4 and (hopefully, at some point) multi-version support.

Michael, are these specific plans described anywhere that we could read?  Or would you be able to describe them briefly?

Curious to know what is planned there.

Thanks,

Andy

[Michael Klishin]

2012/10/5 Andy Fingerhut <andy.fi...@gmail.com>

Michael, are these specific plans described anywhere that we could read?  Or would you be able to describe them briefly?

Curious to know what is planned there.

We are currently migrating CDS to the same toolchain clojurewerkz.org sites use. Doing so will let us

not reinvent some wheels and it's the devil we know. This should be done early next week.

The plan is to have a flat list of guides organized in 3 groups:

 * Tutorials

 * Language guides

 * Tools & Ecosystem guides

You can read about the difference in the README:

https://github.com/clojuredocs/cds/blob/master/README.md

There are no grand plans for the guides, just write, edit, deploy, gather feedback, rinse and repeat.

We already have a list of guides to help people who want to contribute pick a topic. An example of such TOC:

http://clojureelasticsearch.info/articles/guides.html

All development will happen on GitHub, with pull requests. We picked CC BY 3.0 as the license for all content:

http://creativecommons.org/licenses/by/3.0/

And then there is the API reference part. The goal is to rewrite clojuredocs.org source parser to produce

JSON and migrate DB schema to support multiple versions. Ideally, clojuredocs.org will be Clojure end to end.

But this will take a while and the reference part is not nearly as bad as it is with the guides and tutorials.

CDS will not have the reference part. It will link to existing resources, be it clojuredocs.org or something else.

I want to stress that one of the major goals (maybe the most important) of all this is to be contributor-friendly. Contributing a spelling fix or improving wording of something should take minutes, not weeks. Everybody should

be able to quickly submit an improvement. Documentation guides on the language is its face for potential

users and there is no shortage of smart people who *want* to improve the situation with the docs, but currently

find it too inconvenient or have no opportunity to do so because of the CA submission process.

There will be something to show next week. I hope this answers your question.

[Michael Jaaka]

why don't you use advantage of html and split the site into two panes
on left the table of content in hiperlink form and on the right the content reloaded on clickin in link in toc
also use numbers for chapters and subchapters
dont use bullets for lists, its harder to make references
also add disqus.com to allow for comments (like on mysql docs)
and your site will be at least useful for someone and treated as reference doc site

[aboy021]

+1 to lowering the barrier to entry for contributing to the community.

One of the much lauded features of Git is that it can be used to create a "network of trust". In principle this means you can open your repo up to anyone, but by being choosy about the pull requests you accept you can control what's going to get in. 

This is perfect for something like documentation.

Also, as it's been said before, a pen and paper CA is a pain.

[Softaddicts]

This insistence on the so-called "CA pain" seems to me overemphasized.
It's a one shot process.

Even if it takes 4 weeks for the paper to reach its destination, it does not
prevent anyone from starting to work on some contribution. The CA
needs to be in by the time the work is about to get published, not by the time
you start to contribute.

My writing is horrible, worst than a doctor, I hate filling forms by hand but I
was able to fill the CA, stamp it and drop it in the mailbox in less than 10 mns.

I live in Canada close to the US, I can understand the frustration if you have to drop
by your local post office if it needs to get stamped over there but one time
processes like this rarely benefit from an optimization.

I would be surprised that we end up with >250,000 contributors in the next
3 years. There is simply not enough Clojure wired brains out there to get to
numbers like the above.

If it ever happens, you can bet than Clojure Core will come out
with something to avoid being flooded by papers if it is legally feasible.

Laws in many countries have been slow to move to consider
electronic formats as legally binding documents.
This may well be why a written CA is needed considering that contributors come
different countries. What may seem obviously legal in one country may not be legal
at all in another.

Better documentation is to me by far a more urgent priority to attract newbies
than allowing CAs to be submitted electronically given the legal fees involved just
to get an opinion about its feasability.

Luc P.

> +1 to lowering the barrier to entry for contributing to the community.
>
> One of the much lauded features of Git is that it can be used to create a
> "network of trust". In principle this means you can open your repo up to
> anyone, but by being choosy about the pull requests you accept you can
> control what's going to get in.
>
> This is perfect for something like documentation.
>
> Also, as it's been said before, a pen and paper CA is a pain.
>
>
> On Friday, 5 October 2012 08:26:39 UTC-5, Mayank Jain wrote:
> >
> >
> >

> > On Fri, Oct 5, 2012 at 6:54 PM, Michael Klishin <michael....@gmail.com<javascript:>
> > > wrote:
> >
> >>
> >>
> >> 2012/10/5 Michael Fogus <mef...@gmail.com <javascript:>>

> >>
> >>> You say that as if it's a bad thing. I'm of the opinion that these
> >>> kinds of efforts should have a low barrier to contribution and be fun.
> >>>
> >>
> >> My apologies, I did not imply that it is a bad thing, only that it is not
> >> entirely clear what direction the project
> >> will take. While for CDS it is pretty clear (at least to people who have
> >> started it).
> >>
> >> While we are at this fun stuff, can we also make the CA submission
> >> process fun?
> >>
> > +1
> >
> >>
> >> --
> >> 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 clo...@googlegroups.com<javascript:>

> >> 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 <javascript:>

> >> For more options, visit this group at
> >> http://groups.google.com/group/clojure?hl=en
> >>
> >
> >
> >
> > --
> > Regards,
> > Mayank.
> >
>
> --
> 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
--

Softaddicts<lprefo...@softaddicts.ca> sent by ibisMail from my ipad!

[Jay Fields]

The CA process isn't what stops me from contributing, the post a patch
to Jira is what seems broken to me. I don't even remember how to
create a patch. Clojure is on github - we live in a fork & pull
request world, it's time for Clojure to get on board with that.

I once noticed that a Clojure fn didn't have a type hint on a return
value. Adding ^String made a substantial performance difference. Not
knowing the process, I forked, and did a pull request. I got this
response:

"Clojure projects cannot accept pull requests so all issues need to be
logged in the appropriate JIRA project and patches can be accepted
from people who have a signed Contributor's Agreement on file:

http://clojure.org/contributing
http://clojure.org/patches"

Which is informative and correct, but, do you really think I'm going
to go through that trouble? If you said yes, you're wrong.

Cheers, Jay

[John Gabriele]

On Saturday, October 6, 2012 12:03:00 PM UTC-4, Jay Fields wrote:

I once noticed that a Clojure fn didn't have a type hint on a return
value. Adding ^String made a substantial performance difference. Not
knowing the process, I forked, and did a pull request. I got this
response:

"Clojure projects cannot accept pull requests so all issues need to be
logged in the appropriate JIRA project and patches can be accepted
from people who have a signed Contributor's Agreement on file:

http://clojure.org/contributing
http://clojure.org/patches"

Which is informative and correct, but, do you really think I'm going
to go through that trouble? If you said yes, you're wrong.

In cases like this, how would Core react if you just emailed clojure-dev with "hi, noticed $issue, is this a bug?"?

Though, I just remembered, it can take some time to get approved to post on the clojure-dev ML. Hm.

---John

[Softaddicts]

I do not agree at all with you. Any piece of software that gets used widely
needs to be maintained with some formal process otherwise there's no way
to insure consistency of future releases. It gets worse as you increase
the # of people that can modify code.

Tickets may seem to you as overhead but it's a decent way to track issues and
fixes according to release plans.

Looking at a bunch of commits in git is limited compared to dedicated
ticket logging solutions like Jira. Providing patches attached to the ticket links
the ticket to the code in git is much more usable.

Refusing pull requests is a way to force issues to be logged in Jira.
The main entrance gate is in Jira, not the other way around.

Clojure is not the only open source projects driven by a ticket reporting
system.

This may look as overhead to you but it is still lighter than similar
processes in many software businesses.

You can report the kind of problems you highlighted on the mailing list
so at least others can take ownership of the issue if you do not feel
inclined to post it in Jira.

Luc

[Andy Fingerhut]

I don't always remember how to create a patch, either, but I do remember where to go to get the short instructions to do so in case I forget. In case you are curious, the process for creating a patch is documented here, under the heading "Developing and submitting patches to Clojure and Clojure Contrib". This page is linked to from the contributing and patches pages you give links for in your message.

http://dev.clojure.org/display/design/JIRA+workflow

On my screen it is about 2 1/2 screenfuls. If you would prefer not to go through those steps, I understand, but it isn't terribly arcane.

Andy

[Andy Fingerhut]

I would agree that the CA pain is overemphasized if the submitter lives in the USA or Canada. It isn't difficult at all.

I have since heard that to get a letter from Russia to the USA, there are several methods, but they range from inexpensive-but-can-take-months-and-are-unreliable, to quick-and-reliable-but-$200.

Those are significantly higher barriers than for developers based in the USA and Canada, where it is a 44 cent stamp and a few days to get there quite reliably.

Andy

[Michael Klishin]

2012/10/7 Softaddicts <lprefo...@softaddicts.ca>

I do not agree at all with you. Any piece of software that gets used widely
needs to be maintained with some formal process otherwise there's no way
to insure consistency of future releases. It gets worse as you increase
the # of people that can modify code.

Sorry, have you tried reading what people who complain about the CA submission process

actually complain about? They do not complain about having the CA. They are not eager to

jump in working on the language. They complain about being shut out from contributing *anything*

(including documentation and updates to libraries like data.json) by the requirement

that CA has to be mailed in paper, in the year 2012.

We have posted examples of projects and corporations that accept PDFs over email:

Oracle, OpenJDK, Apache Software Foundation, Neo4J. Scala and Opscode found more creative solutions

that use OAuth and similar techniques.

As far as the number of language designers, I think there is little disagreement that the number Clojure has right now

(1 or 2, with some influence from maybe 5-6 more) is about optimal. There is much more to success and adoption

of Clojure than just language features, design, consistency and other things that may benefit from this "tight grip".

 

Tickets may seem to you as overhead but it's a decent way to track issues and
fixes according to release plans.

Looking at a bunch of commits in git is limited compared to dedicated
ticket logging solutions like Jira. Providing patches attached to the ticket links
the ticket to the code in git is much more usable.

Refusing pull requests is a way to force issues to be logged in Jira.
The main entrance gate is in Jira, not the other way around.

This is all handwaving. You can use a bug tracker and plan the hell out of releases on github.

Many projects do so. However, how quickly contributions are accepted matters a lot for smaller improvements

like the Jay's example.

Go take a look at repositories under github.com/clojure, you will find 10-20 people contributing small improvements

and being rejected every single month. Do you really think most of them actually will come back? Do you have the

guts to say they should not be considered valuable members of the community because of that?

If you make something difficult or time consuming, people will do it less.

 

Clojure is not the only open source projects driven by a ticket reporting
system.

This may look as overhead to you but it is still lighter than similar
processes in many software businesses.

You can report the kind of problems you highlighted on the mailing list
so at least others can take ownership of the issue if you do not feel
inclined to post it in Jira.

It's about even having a chance to participate. JIRA and patches are annoying to anyone who has used github for

at least a few months but it is not really a big deal to anyone I know who is unhappy about the situation.

It is all about the fact that if you do not live in North America or western Europe, you are shut out of the game.

And the reason why CDS distances itself from Clojure/core and the existing process as far as possible is to at least give Clojure users

a chance to help with the biggest pain point: documentation.

[Rich Hickey]

On Oct 6, 2012, at 12:02 PM, Jay Fields wrote:

> The CA process isn't what stops me from contributing, the post a patch
> to Jira is what seems broken to me. I don't even remember how to
> create a patch. Clojure is on github - we live in a fork & pull
> request world, it's time for Clojure to get on board with that.
>

Lots of people eat fast food as well.

> I once noticed that a Clojure fn didn't have a type hint on a return
> value. Adding ^String made a substantial performance difference. Not
> knowing the process, I forked, and did a pull request. I got this
> response:
>
> "Clojure projects cannot accept pull requests so all issues need to be
> logged in the appropriate JIRA project and patches can be accepted
> from people who have a signed Contributor's Agreement on file:
>
> http://clojure.org/contributing
> http://clojure.org/patches"
>
> Which is informative and correct, but, do you really think I'm going
> to go through that trouble? If you said yes, you're wrong.

I'm responding to Jay here (because we're friends and I know he can take it:), but this is for everyone who feels similarly:

I prefer patches. I understand some people don't. Can't we just agree to disagree? Why must this be repeatedly gone over?

I'm not sure what value you think a message like this is going to provide to the thousands of participants in this list. Does it make you feel better? It will not convince me otherwise.

Here's how I see it. I've spent at least 100,000x as much time on Clojure as you will in the difference between producing a patch vs a pull request. The command is:

git format-patch master --stdout > your-patch-file.diff

There are two sides to change management - production/submission, and management/assessment/application/other-stewardship. People who argue that the process should be optimized for ease of submission are simply wrong. What if I said patches were twice as efficient for me to assess and manage as pull requests? (it's more than that) Do the math and figure out how the effort should best be distributed.

I don't think asking for patches is asking too much, and I truly appreciate the people who are going to the extra effort. And, I respect the fact that people disagree, and they might decide not to participate as a result. However, I don't need to justify my decision over and over. How about a little consideration for me, and the other list participants? There is a real diluting effect of get-it-off-my-chest messages such as these on the value of the list and the utility of reading it for myself and others.

Sometimes it's better to save it for your bartender :)

Rich

[Softaddicts]

The validity of a scanned signature or electronic keys is subject to interpretation
and assessment on a per case basis especially in civil contracts by the diverse
legal systems on Earth.

It's not the Clojure community that is behind, it's the legal systems of many countries
that did not follow the pace of technology. Some will not recognize scanned signatures
at all.

On the other hand, original hand written signatures are recognized almost every where.

As much as you complain about the paper CA, you should complain about
the legal systems of these countries that do not follow US and western Europe
attempts to recognize technology changes and adapt to it.

You analyze the issue by the wrong end

It's not a technology issue, it's a legal one.

You could have the best electronic authentication scheme, if it's not
recognized by a country's legal system, it's useless in court in this country.
If claims rights on contributions not backed by a CA in a valid form as defined in this
country, it's a lost case.

Big organizations have the tools and budgets to fight in various legal systems
out there. Not small open source projects or projects without big sponsors.

I understand and approve the requirement of the original hand written signature in
this context. That's a real life issue that cannot be dealt with by technology alone.

If a national mail system is not able to get reliably an envelope to the US
within 4/5 weeks, I would be very concerned about the state of their legal system.

Luc

[aboy021]

It would be nice if there were an alternative to the CA for small documentation contributions.

Wikipedia is largely built up from a small pool of dedicated people but many valuable contributions come from small anonymous edits.

[Softaddicts]

For documentation purposes, I think it could be relaxed but it would still need
some reviewing process. The main concern here's is to avoid cloning other published
stuff with legal rights either intentionally or not.



Luc P.

> > > 2012/10/7 Softaddicts <lprefo...@softaddicts.ca <javascript:>>

> > > To post to this group, send email to clo...@googlegroups.com<javascript:>

> > > 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 <javascript:>

> > > For more options, visit this group at
> > > http://groups.google.com/group/clojure?hl=en
> > --

> > Softaddicts<lprefo...@softaddicts.ca <javascript:>> sent by ibisMail from

[Michael Klishin]

2012/10/7 Softaddicts <lprefo...@softaddicts.ca>

The validity of a scanned signature or electronic keys is subject to interpretation
and assessment on a per case basis especially in civil contracts by the diverse
legal systems on Earth.

It's not the Clojure community that is behind, it's the legal systems of many countries
that did not follow the pace of technology. Some will not recognize scanned signatures
at all.

On the other hand, original hand written signatures are recognized almost every where.

A reminder: scans work for Oracle and ASF. Oracle probably has x100 as many lawyers as

Clojure/core, lawyers several times as experienced and about x10,000 times as much experience with this stuff as a company. And it works for them.

 

As much as you complain about the paper CA, you should complain about
the legal systems of these countries that do not follow US and western Europe
attempts to recognize technology changes and adapt to it.

You analyze the issue by the wrong end

It's not a technology issue, it's a legal one.

You could have the best electronic authentication scheme, if it's not
recognized by a country's legal system, it's useless in court in this country.
If claims rights on contributions not backed by a CA in a valid form as defined in this
country, it's a lost case.

Big organizations have the tools and budgets to fight in various legal systems
out there. Not small open source projects or projects without big sponsors.

I understand and approve the requirement of the original hand written signature in
this context. That's a real life issue that cannot be dealt with by technology alone.

If a national mail system is not able to get reliably an envelope to the US
within 4/5 weeks, I would be very concerned about the state of their legal system.

Sorry to break it to you, but legal systems outside of a few countries are seriously

broken and it will take decades and many lives to fix this. And I assure you, people who

live in those countries are just as concerned as you are, thanks for caring.

So the system is how it is. Clojure/core can 

accept this unfortunate fact and find a way to accept CA submissions electronically.

Or they can ignore all the complaints (again, not about the CA per se, but how it is currently submitted) and lose many potential contributions.

Contributions from people who really want to make Clojure better, ready to spend

many hours of their time contributing but were not lucky enough to be born in the Wonderland called Canada, where the law rules and the sun shines (at least 2 months of the year).

It always starts with contributing something small. Then something else small.

Then something slightly more significant. And next thing you know, you are a major

contributor. That's how it started for every single active OSS contributor I know.

[Ben Mabey]

On Oct 6, 2012, at 6:04 PM, Michael Klishin <michael....@gmail.com> wrote:

2012/10/7 Softaddicts <lprefo...@softaddicts.ca>

The validity of a scanned signature or electronic keys is subject to interpretation
and assessment on a per case basis especially in civil contracts by the diverse
legal systems on Earth.

It's not the Clojure community that is behind, it's the legal systems of many countries
that did not follow the pace of technology. Some will not recognize scanned signatures
at all.

On the other hand, original hand written signatures are recognized almost every where.

A reminder: scans work for Oracle and ASF. Oracle probably has x100 as many lawyers as

Clojure/core, lawyers several times as experienced and about x10,000 times as much experience with this stuff as a company. And it works for them.

I thought the CA for chef had a pretty slick online process:

https://secure.echosign.com/public/hostedForm?formid=PJIF5694K6L

-Ben

[Max Penet]

Google also has something similiar, and it has probably been checked by an army of layers.

http://code.google.com/legal/individual-cla-v1.0.html

[Softaddicts]

It works for Oracle because they have the $$$ to support it. You just confirmed
that we are on the same wavelength, they have the weapons to nail anyone who
would like to exercise exclusive rights on some contribution made under their CA
even if that individual lives in Kazakhstan.

They have the infra structure and several offices in various
Countries and continents to cover their ass.

Just to keep in touch with our marvelous legal systems in North America, read this:

http://hrdailyadvisor.blr.com/archive/2010/08/20/Epinions_Employment_Law_Update_Scanned_Documents.aspx

The first question/answer is pretty instructive. It's easier to avoid the whole issue
with a piece of paper. Maybe in ten years things will have settled somehow.
The above is dated from 2010 that's not far away.

I will not anything else to this thread, the world is as it is. I you think that you are
frustrated, maybe we should have a drink together and I could explain how
much I am frustrated by this shattered world....

Do you expect to drop at the Conj ?

Luc

[nchurch]

> Just to keep in touch with our marvelous legal systems in North America, read this:

...

> how much I am frustrated by this shattered world....

Indeed! The law is nothing but an overly complex, haphazardly
designed, historically encrufted programming language for morals.

Its compiler is frighteningly well-maintained, though.

On Oct 6, 6:24 pm, Softaddicts <lprefonta...@softaddicts.ca> wrote:
> It works for Oracle because they have the $$$ to support it. You just confirmed
> that we are on the same wavelength, they have the weapons to nail anyone who
> would like to exercise exclusive rights on some contribution made under their CA
> even if that individual lives in Kazakhstan.
>
> They have the infra structure and several offices in various
> Countries and continents to cover their ass.
>
> Just to keep in touch with our marvelous legal systems in North America, read this:
>

> http://hrdailyadvisor.blr.com/archive/2010/08/20/Epinions_Employment_...

>
> The first question/answer is pretty instructive. It's easier to avoid the whole issue
> with a piece of paper. Maybe in ten years things will have settled somehow.
> The above is dated from 2010 that's not far away.
>
> I will not anything else to this thread, the world is as it is. I you think that you are
> frustrated, maybe we should have a drink together and I could explain how
> much I am frustrated by this shattered world....
>
> Do you expect to drop at the Conj ?
>
> Luc
>
>
>
>
>
>
>
>
>

> > 2012/10/7 Softaddicts <lprefonta...@softaddicts.ca>

> Softaddicts<lprefonta...@softaddicts.ca> sent by ibisMail from my ipad!

[gaz jones]

While on this topic, is it possible for someone with admin privileges
to disable the "Issues" tabs in the contrib projects? There is a
consistent drip of people sending pull requests or opening bugs which
have to be redirected to JIRA. All of the contrib projects now point
to JIRA in the README for both these things.

[John Gabriele]

On Sunday, October 7, 2012 9:32:45 PM UTC-4, Gaz wrote:

While on this topic, is it possible for someone with admin privileges
to disable the "Issues" tabs in the contrib projects? There is a
consistent drip of people sending pull requests or opening bugs which
have to be redirected to JIRA. All of the contrib projects now point
to JIRA in the README for both these things.

Maybe ping this thread (which I see you participated in) listing the libs that still have "Issues" enabled:

https://groups.google.com/forum/?fromgroups=#!topic/clojure-dev/9ZTZXdBR6XU

---John

[Bill Robertson]

Giant +1 to moving clojuredocs.org forward. I've been getting concerned about the longevity of the site, and I would really miss it if it were gone.

On Thursday, October 4, 2012 4:35:33 PM UTC-4, Michael Klishin wrote:

2012/10/5 Bronsa <brob...@gmail.com>

Wouldn't it be better for readevalprintlove and clojuredocs to join forces from the beginning?

It's not clear what readevalprintlove wants to be. clojuredocs has been discussed for a while by some people who care

about Clojure documentation. There are pretty specific plans about the guides and moving clojuredocs.org forward

to 1.4 and (hopefully, at some point) multi-version support. In part the guides portion of clojuredocs (the organization)

will follow the clojurewerkz.org projects model which is known to work well and even produced some tools

we can easily reuse and adapt.

readevalprintlove looks like a fancy playground so far.

There are multiple aspects to good documentation, see http://jacobian.org/writing/great-documentation/

[Andy Fingerhut]

Michael, thanks for the detailed response, and I appreciate the effort you are putting forth in the clojure-doc.org site.

I do have some followup questions on clojuredocs.org, since you gave some description of what you hope and/or expect to happen there.

On Oct 5, 2012, at 1:52 PM, Michael Klishin wrote:

And then there is the API reference part. The goal is to rewrite clojuredocs.org source parser to produce

JSON and migrate DB schema to support multiple versions. Ideally, clojuredocs.org will be Clojure end to end.

But this will take a while and the reference part is not nearly as bad as it is with the guides and tutorials.

*Whose* goal is it to make those changes to clojuredocs.org?

Someone that is willing and able to write the code, has the time to do it, and is authorized to make changes to the clojuredocs.org site?

I ask not because I expect anyone to make these changes, but because you sound like you might know the answer, i.e. maybe you have been in communication with those people.

Thanks,

Andy

[Michael Klishin]

2012/10/10 Andy Fingerhut <andy.fi...@gmail.com>

*Whose* goal is it to make those changes to clojuredocs.org?

Someone that is willing and able to write the code, has the time to do it, and is authorized to make changes to the clojuredocs.org site?

I ask not because I expect anyone to make these changes, but because you sound like you might know the answer, i.e. maybe you have been in communication with those people.

About two weeks ago, after yet another heated discussion about the state of Clojure documentation in #clojure on irc.freenode.net, a few people decided to start working on CDS. As part of that discussion we had to ask ourselves

the question "what will we do about API reference and clojuredocs.org?". It turns out, someone already has

a pretty good idea of what needs to be done and has contact to the original author.

I focus on the guides part of things and not super up-to-date about the state of clojuredocs.org revamp. It may

or may not start soon.

If anybody wants to join people behind CDS, #clojuredocs on freenode.

HTH,
--
MK

[Michael Klishin]

2012/10/10 Michael Klishin <michael....@gmail.com>

If anybody wants to join people behind CDS, #clojuredocs on freenode.

We changed it to #clojure-doc to register it properly and make it match the domain.
--
MK

[Lee Hinman]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Andy,

On 10/10/12 1:30 PM, Andy Fingerhut wrote:
> Michael, thanks for the detailed response, and I appreciate the
> effort you are putting forth in the clojure-doc.org

> <http://clojure-doc.org> site.

>
> I do have some followup questions on clojuredocs.org

> <http://clojuredocs.org>, since you gave some description of what

> you hope and/or expect to happen there.
>
> On Oct 5, 2012, at 1:52 PM, Michael Klishin wrote:
>
>> And then there is the API reference part. The goal is to rewrite

>> clojuredocs.org <http://clojuredocs.org/> source parser to

>> produce JSON and migrate DB schema to support multiple versions.

>> Ideally, clojuredocs.org <http://clojuredocs.org/> will be

>> Clojure end to end. But this will take a while and the reference
>> part is not nearly as bad as it is with the guides and
>> tutorials.
>
> *Whose* goal is it to make those changes to clojuredocs.org

> <http://clojuredocs.org>?

It's my goal, I have already have an extractor
(https://github.com/dakrone/lein-clojuredocs) that works for leiningen
projects as well as clojure's source. What is currently lacking is an
import workflow as well as some kind of frontend to transition the
existing examples to.

> Someone that is willing and able to write the code, has the time to
> do it, and is authorized to make changes to the clojuredocs.org

> <http://clojuredocs.org> site?

I also have access to the machine that clojuredocs.org is running on,
and the credentials for the MySQL database, having developed the
current API and helping Zach get it started.

> I ask not because I expect anyone to make these changes, but
> because you sound like you might know the answer, i.e. maybe you
> have been in communication with those people.

Feel free to ping me on irc (dakrone) if you want to talk more about
it, or jump into the #clojure-doc IRC room.

- - Lee Hinman

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (Darwin)
Comment: Using GnuPG with Mozilla - http://www.enigmail.net/

iQIcBAEBAgAGBQJQdfGVAAoJEJ1kZdQ6zsrgbYEP/3GBOZWelF6GKziaolpFpoDz
q0rGitrkVyLBCwxtbChDj9KXyDu62rWtBLRbID3uBfxZRdWrAdDqo5NKCX9QrkQh
W7qQb6j8rlJEuwlJZVn7ZlwP7S2fxugTtLt0p7RUW1Mzr5vokfiLkjkawvPfE0vk
3T6B7a0BPznkNne2xtv1x/Urn2bB+faku6Kqs0xcvvRtzXC/jHhQ5nKzYr4xzh/m
Ge9xVXLkpef0USlKe26v8jt06aGJvz/xQC40Djzeb8X+II+8ryo/uOa/bFqEnfpR
lYkbyODkSKzzuJoY/zTlhtI+mcPYre6q8i+Kkgh7LUl6C8kmpBDD2NprS8O10ZI8
037goOnJDZLIjG/bvjtWEvlfAgttMhye34k5rBVxR742Q14WcLaS4mbn2QTF7b4h
+BFncDyMKyRp9aE3Xg3EcMmG9Jj7vopPJHQwdCJwXJKwc0QSZxQEn6lW/AYPOeXe
qnJx3sue1aIdWM3KqC4fvlt9OBrGWXav53ERGfL7uDhvx5j1nWW3N5wUm5D3l6cj
fHWbkJgKrSRjNHdckcL+s0uATF/NZAVBVeqy4C1T6zLKeayLRCzPaQmlt/GUmIMq
DifTLKTIMNFfGH+5VcHYsr4jiuxnOoIgvR7evKSxDmfIKb0yPNKry3QzINFEuA9J
1EVt3g7zVYCp/F7eIWnl
=Itve
-----END PGP SIGNATURE-----