On Mon, Jun 25, 2012 at 9:52 PM, John Gabriele <jmg3...@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 -- 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
