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