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