cgrand/enlive — pull request #42 by ddellacosta (2012-09-06 12:50:18+00:00)
Title: Proposal for Revisions to Documentation

Hi Christophe,

I'm proposing some somewhat significant changes to the docs. As a Clojure beginner, I have to be honest and say I found even understanding what Enlive does to be rather confusing. But after investigating I realized what a great library it is, and I wanted to suggest some changes that I thought would make it easier for beginners to pick it up more quickly.

This includes presenting a simple example of what it does right off the bat, and including documentation for something which I have found painful when working with other Clojure libraries: how to include it in a lein project.clj file as well as how to call the library from one's source code. I also restructed the sections to flow in what I think you agree is a more natural order and more consistent with other projects.

One change I'm made that's not strictly necessary is changing the readme from textile to markdown--I did this so I could use some of the formatting (specifically Clojure-specific syntax highlighting) which Github provides. But if you don't care for it, I'll re-format it as textile.

What I'm including in the pull request is not complete, but I thought it would give you a good sense of what I'm proposing. I would also like to suggest moving some of the other more comprehensive information on selector syntax and transformations to separate wiki pages, if you think it would make sense, but I figured I would wait first to hear what you thought generally about the changes I'm suggesting.

Finally, I'll add that I've also incorporated the edits from these two pull requests:

https://github.com/cgrand/enlive/pull/32
https://github.com/cgrand/enlive/pull/31

So, if you accept this pull request (at some point) you should be able to close those two as well.

Let me know what you think--in any case, I'd love to help out somehow, so feel free to suggest another approach to the documentation if you don't care for what I'm proposing.

Thanks for the great library!

Best,
Dave