{ANN} Project Docs and Examples ... at the Alcove

[John Gabriele]

Hi all,

I was looking for a way to:

* encourage folks to write docs for their Clojure projects
* make usage examples available (like clojuredocs.org has, but for
general Clojure-related projects)
* help semi-standardize how Clojure projects are documented

So I made this:

http://www.unexpected-vortices.com/alcove/index.html

("The Alcove" seemed like a nice name for a quiet place to read docs
and examples.)

There are only a few projects listed there so far. If you know of
others you think would benefit from being there (or if you'd like to
write some examples for a project), let me know and I'll add them.

Pages at the alcove are generated from:

* project README.md (if present) and doc/*.md files (if present)
* user-submitted examples (.md files in a separate repository ---
one .md file for each project)

Some benefits of this approach:

* most projects will not have to change they way they set up their
project (most already at least have a README.md file)

* Markdown is a handsome and easy markup format that the Clojure
community seems to have embraced (used in READMEs; Marginalia uses it;
my understanding is that autodoc may eventually support it).

* Most folks already know Markdown (it's what github, reddit, and
stackoverflow use), or can pick it up in a few minutes.

* doesn't tie the community to any one system. You're simply
encouraging authors to create a flat directory of text files in a
top-level doc directory.

* The alcove-examples repository is just one text file per project.
Nothing that ties anyone to "The Alcove" site.

* examples files on github means people can see who contributed
which examples; it's fun to see your name in lights. :)

* the alcove uses Pandoc to render markdown, and so supports some
things that github's markdown does not, such as tables, definition
lists, LaTeX math, and a few other features.

Drawbacks:

* currently only supports projects on github
* currently, additions/updates are done manually (via a couple of
scripts and rsync).
* currently not many projects have a doc directory present
* currently hosted on my tiny shared hosting site

Questions:

* do contrib projects belong on the Alcove?
* will users benefit very much from having example code for projects?
* will users contribute examples?

Possibilities:

* possible cooperation with clojuredocs.org? (ex.
"www.clojuredocs.org/alcove/..." ?)
* possible hosting elsewhere? Perhaps on a more clojure-specific domain?
* perhaps switch to a more general github username instead of my own?

Opinions? Concerns? Wild praise? Searing complaints? General disinterest?

Thanks!
---John

[Michael Klishin]

John Gabriele:

> Opinions? Concerns? Wild praise? Searing complaints? General disinterest?

This is a great initiative but so far it seems to focus only on the API reference part of documentation.
I personally think that documentation guides are just as important [1].

For clojurewerkz.org projects, we put doc guides first:

http://clojuremongodb.info
http://clojureriak.info
http://clojureneo4j.info

and so on. It would be nice to see Alcove address that part, too.

1. http://jacobian.org/writing/great-documentation/

MK

mic...@defprotocol.org

[Vinzent]

It's a great initiative indeed, but I found the project pretty useless in its current state. Forking the repo and sending a pull request just to add an example is painful. Also, I can read rendered readme on github (and have the source code at hand), so why go to another site?

I think what would be really good is the possibility to add user projects to clojuredocs.org. Every user who has an account should be allowed to add his own project, which will reuse all the clojuredocs infrastructure (comments, examples, links to the source). Readme and stuff like links to clojars and github pages could be displayed on the project's main page.

However, there is a little problem with that: clojuredocs is written in RoR, AFAIK. What about rewriting it in clojure+clojurescript, anybody? :)

As for non-API part of documentation, I think github's wiki is pretty good for this purpose. I'd personally won't use another site which provides similar functionality just because it was created specifically for clojure projects. 

понедельник, 25 июня 2012 г., 9:32:17 UTC+6 пользователь John Gabriele написал:

Hi all,

I was looking for a way to:

  * encourage folks to write docs for their Clojure projects
  * make usage examples available (like clojuredocs.org has, but for
general Clojure-related projects)

  * help semi-stanordize how Clojure projects are documented

[John Gabriele]

On Jun 25, 12:14 am, Michael Klishin <michael.s.klis...@gmail.com>
wrote:

> John Gabriele:
>
> > Opinions? Concerns? Wild praise? Searing complaints? General disinterest?
>
> This is a great initiative but so far it seems to focus only on the API reference part of documentation.

I'd think that autogenerated docstring docs would be api-focused. The
Alcove only has doc/*.md docs (plus examples) --- not necessarily API
docs at all.

> I personally think that documentation guides are just as important [1].

I agree. My thought is that authors would put their guides into doc/
*.md files.

---John

> For clojurewerkz.org projects, we put doc guides first:
>
> http://clojuremongodb.infohttp://clojureriak.infohttp://clojureneo4j.info

Certainly handsome docs. :)

---John

[John Gabriele]

On Jun 25, 12:52 am, Vinzent <ru.vinz...@gmail.com> wrote:
> It's a great initiative indeed, but I found the project pretty useless in
> its current state. Forking the repo and sending a pull request just to add
> an example is painful.

Hm. Thanks for the feedback.

> Also, I can read rendered readme on github (and have
> the source code at hand), so why go to another site?

1. centralized location for docs (easy to find your way to other
project docs)
2. the examples
3. more featureful rendering (I'm using Pandoc for the alcove, and so
it supports extra markdown syntax for things like tables, definition
lists, LaTeX math, and a few other goodies.)

> I think what would be really good is the possibility to add user projects
> to clojuredocs.org.

That would be nice.

> Every user who has an account should be allowed to add
> his own project, which will reuse all the clojuredocs infrastructure
> (comments, examples, links to the source). Readme and stuff like links to
> clojars and github pages could be displayed on the project's main page.
>
> However, there is a little problem with that: clojuredocs is written in
> RoR, AFAIK. What about rewriting it in clojure+clojurescript, anybody? :)

I'm also curious about this.

> As for non-API part of documentation, I think github's wiki is pretty good
> for this purpose. I'd personally won't use another site which provides
> similar functionality just because it was created specifically for clojure
> projects.

That's true. The github wiki's could be used for example code too.
Though, I don't see it used much for that. Perhaps a dedicated site
like the alcove would encourage more contributions of example code?

Also, I think there's something to be said for having all the examples
in one place --- one repo that anyone can grab and have the full
collection. (Though, perhaps clojuredocs.org could support that too.)

If clojuredocs.org were to be extended to support adding 3rd-party
projects, would users prefer to put example code there, or in the
project's github wiki?

Thanks for the feedback.

---John

[Vinzent]

One thing I forgot to mention: it'd be nice to have Marginalia support, since it can be used not only for annotated source code, but also for documentation with embedded tests (although, two-column layout doesn't fit very well for this purpose, but it's another question). 

 

That's true. The github wiki's could be used for example code too. 

Though, I don't see it used much for that. Perhaps a dedicated site
like the alcove would encourage more contributions of example code?

Sure, if every visitor would see a big red button titled "Add an example!" there'd be much more chances that some examples will be contributed :)

Also, I think there's something to be said for having all the examples
in one place --- one repo that anyone can grab and have the full
collection. (Though, perhaps clojuredocs.org could support that too.)

For me personally it doesn't matter; maybe someone else would find it useful.

 

If clojuredocs.org were to be extended to support adding 3rd-party
projects, would users prefer to put example code there, or in the
project's github wiki?

I think authors who prefer github's wiki would rather continue use it, but the important thing that anybody interested would have the right place to add snippets, comments, etc.

Honestly, what I'd really appreciate is a full-blown community site, kind of mix between clojure-toolbox, clojuredocs and emacswiki.

[John Gabriele]

On Jun 25, 2:36 am, Vinzent <ru.vinz...@gmail.com> wrote:
>
> Honestly, what I'd really appreciate is a full-blown community site, kind
> of mix between clojure-toolbox, clojuredocs and emacswiki.

I like clojure-toolbox. It's categorization of projects is quite
useful, IMO.

[John Gabriele]

On Jun 24, 11:32 pm, John Gabriele <jmg3...@gmail.com> wrote:
>
> Opinions? Concerns? Wild praise? Searing complaints? General disinterest?
>

Hi all,

Thanks to feeback --- both here and elsewhere. A handful of points are
now clear:

* It probably *is* too much trouble to ask folks to fork & send a
pull-request just to add code examples

* Users who want to add example code can just as well add it to the
project's github wiki. If there's no wiki, they can ask the maintainer
to please enable the wiki.

* If a github project changes maintainer, it's easy enough to clone
the github wiki repo for use by the new maintainer.

* Using github's Markdown for docs is often sufficient. If a user
wants the extra features of Pandoc's enhanced-Markdown, nothing's
stopping them from using that and generating html themselves.

* The categorized listing of modules at clojure-toolbox is nicer
than a flat listing like at the alcove, and I'm not interested in
trying to duplicate effort there.

* The community seems (to me) to be headed toward standardizing on
doc/*.md files for docs regardless, since github automatically renders
them nicely and everyone already knows markdown and writes README.md
files.

* The community seems pretty happy with Clojars + Github. The only
issue I have is that some projects there don't have their :url and/
or :description keys properly set (thus they're not displayed (or
don't contain anything useful) at Clojars). But we can add the
relevant info over time.

* If clojuredocs.org is rewritten in Clojure, I'm guessing a 3rd-
party project examples feature could be added pretty easily if it
turns out users really want it.

So, it now seems that the alcove --- in its current incarnation --- is
not as useful as I'd originally thought. I'm going to remove it, and
instead focus on helping make sure projects on Clojars have their :url
and :description in order.

Thanks!
---John

[Michael Klishin]

John Gabriele:

> So, it now seems that the alcove --- in its current incarnation --- is
> not as useful as I'd originally thought. I'm going to remove it, and
> instead focus on helping make sure projects on Clojars have their :url
> and :description in order.

John,

Please don't get discouraged. There are similar services (readthedocs.org, rubydoc.info) and they took a while (years) to
get all the tooling, workflows and community awareness to the levels when these services are really useful and adopted.

I personally believe that there is no other thing Clojure needs right now as badly as well written, maintained, good looking documentation for the language itself, clojure.core and most popular open source libraries.

Your attempt is a good start and clojuredocs.org one day will be Clojure end to end (I believe the analyzer part has always been in Clojure).

MK

mic...@defprotocol.org

[John Gabriele]

On Jun 25, 11:58 pm, Michael Klishin <michael.s.klis...@gmail.com>
wrote:

>
> Please don't get discouraged.

Thanks for the kind words, Michael! :) Not discouraged, but rather, I
want to make best use of existing resources.

> There are similar services (readthedocs.org, rubydoc.info) and they took a while (years) to
> get all the tooling, workflows and community awareness to the levels when these services are really useful and adopted.
>
> I personally believe that there is no other thing Clojure needs right now as badly as well written, maintained, good looking documentation for the language itself, clojure.core and most popular open source libraries.

I agree that great docs are a top priority, however, the way they're
currently being provided for external Clojure projects seems to be
pretty good for the time being. I mean, most Clojure projects are
using github, and github happily renders the docs as html. The
ingredients are there. The crucial piece (as I (now) see it) is being
able to find the project you want at Clojars so you can follow the
link to the docs (at github). After doing some reading, if this
project is not your cup of tea, go back to clojure-toolbox or #clojure
(irc), get help choosing something else, and go back to Clojars to
find it.

So, rather than try to duplicate what github is already doing for us
right now, I think it probably makes more sense to spend that time
writing docs and also making sure users can find the relevant github
repo from clojars.

---John

[Phil Hagelberg]

On Mon, Jun 25, 2012 at 9:52 PM, John Gabriele <jmg...@gmail.com> wrote:
> I agree that great docs are a top priority, however, the way they're
> currently being provided for external Clojure projects seems to be
> pretty good for the time being. I mean, most Clojure projects are
> using github, and github happily renders the docs as html. The
> ingredients are there.

Right; the way I see it the two missing pieces are 0) encouraging
library authors to write better documentation and 1) ensuring that
documentation is discoverable.

For 0 one change I've made is to have the default `lein new` skeleton
include a doc/ directory with a pointer to explain what kind of things
to write. There's a temptation to documentation that's autogenerated
from the source code a la Marginalia, but that's really only suited
for reference material, and most libraries need introductory long-form
guides to help people out.
(http://jacobian.org/writing/great-documentation/what-to-write/
addresses this topic well.) The problem here is that it's hard work,
and most maintainers don't prioritize it.

For 1 I think John is right that simply getting projects to declare a
:url that Clojars can link to will make a big difference. If you
maintain a project that doesn't link to its home page from Clojars,
all it takes is the addition of a :url in project.clj. If you use
`lein deploy clojars` it will nag you if you're missing that, so that
should help too. But I think getting maintainers to care about docs is
the big one. It's good to see the ClojureWerkz libraries setting a
good example; I hope others will follow.

-Phil