Proposal for Revisions to Documentation

[ddellacosta]

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:

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

[ddellacosta]

Sorry, I meant to say, "what I think you may agree" above, not "what I think you agree." It sounds a bit presumptuous as is...haha.

[cgrand]

Sorry for the delay your pull request went unnoticed. I'm looking at it. Thanks for the feedback!

[ifesdjeen]

@ddellacosta I will take all your changes and form a new PR if you don't mind. We've already added Travis, and did a couple of smaller changes to the documentation. I've started working on more elaborate Readme.

I'll make sure that all your changes make it to the new Readme version!

[ddellacosta]

@ifesdjeen

That sounds just fine to me--really I wanted to just suggest a way of structuring the docs that would make it a bit more apparent what enlive does and how to get up and running quickly.

I'm happy also to do some rewriting/restructuring if that would be helpful--whatever you think would be useful. In any case, thanks! Oh, and if you think it is appropriate, go ahead and close this (or I can...).

Cheers,
Dave

[ifesdjeen]

@ddellacosta I can't really close anything :) so far, I'm helping @cgrand to clean up issues and pull requests, and putting a 'roadmap' together, so you can close it :)

I'll put a note for myself and will give you a ping as soon there's a new doc/readme/guide structure, cool if you could pitch in there)

[ddellacosta]

Ah, gotcha! I didn't realize, closing...

Yeah, give me a ping, I'd love to help out.