Disqus support

[mads-hartmann]

I think it would be a great idea to use disqus to add comment support to each page to make it even easier for people to give feedback.

I don't mind implementing it and send a pull request to pamflet but I wanted to make sure that you guys also think it's a good idea before going forward :)

/Mads

[d6y]

The only opinion I have is that I'd like to keep the documentation clean and up-to-date. By that I just mean not like the MySQL reference documentation that, to this day, contains comments from people regarding workarounds for MySQL 4; or the Google Code pages, that also have lots of discussion that may or may not be relevant any more. There's the risk of that stuff being a distraction and misleading.

The only related idea I had was to include on each page a link to "edit this page in github", but that's not very friendly I guess. Or "contact the author". Or a mailto: link saying "discuss this on the liftweb mailing list". I am probably being too narrow in understanding how Lift users want to interact with this document :-/

[mads-hartmann]

Here's what I think would be ideal:

People should be able to make a comment on a specific paragraphs of a document or the entire page. This comment would be visible by everyone instantaneously until one of the authors could work the comment into the text and then remove the specific comment. This way it would be extremely fast for the readers to make changes (even fix typos) and we could merge in the changes as we go. And if for a couple of days we don't have time to merge in changes the rest of the readers would still be able to read the comment - I also think it might be motivating for the reads that they can see their feedback instantaneously.

Lets assume we had a system like this - would you think that would be a good idea?

[pr1001]

Mads, it sounds like you're describing the commenting on source code lines that GitHub allows. Since the documentation files are already on GitHub, maybe there should just be a way to have the rendered documentation alert people if there are any conversations about the source file?

[timperrett]

Why don't you just implement: http://ace.ajax.org/build/kitchen-sink.html - all your text files are held as markdown right? Would be a fairly trivial exercise to implement some services to read/write those markdown files. Fairly sure you could mash that together with one of the JVM git libs.

[mads-hartmann]

Yes, if Github has such an API that would actually be awesome! :) Then all we would need would be

• A link to the source file on github with a message like: "Want to contribute? Simply make comments on the source here"
• An api call to Github asking if there are any comments on the source of this page, if there is show a little yellow warning box at the top of the page with a comment like: "This document has additional content that hasn't yet been merged in" and then a link to the source on github

How about that?

[mads-hartmann]

@timperrett But that would require that we move away from pamflet right? Currently the markdown files are only used to generate the static html files so any changes would have to be compiled before they would be visible

(wish github had threaded comments)

[timperrett]

It really depends how far down the "live editing" path you want to go... I mean, thats essentially a wiki, of which there are many impls. If you want to retain authorship control then yeah, you'll have to have some not-instant change functionality or do something around pull requests. Dunno... I wouldn't let pamphlet hold you back in that sense - you may find banging up a quick markdown view in Lift / Unfiltered or whatever would be easier that trying to fit a square peg into a round hole.

Just spitballin'

[mads-hartmann]

I'm pretty happy with the pamflet and the authorship control tbh, I just want to make it easier for people to comment on the texts to keep the readers involved and keep the authors motivated :)

[d6y]

I'm not wedded to Pamflet: all options are open. It does give you a view of the whole contents, so you can scan for something that might match what you're after. It also looks quite nice.

I think the markdown+git combination is a good fit for small chunks of text loosely joined. I avoided a wiki only because Lift already has one (but I don't think the editing experience is very good) and it'd be confusing to add another.

We also have the twitter LiftCookbook account if that would be of use for feedback.

Hmm... each time think of this I keep coming back to the idea of feedback should happen on the mailing list: more eyes and brains there to help people = better chance of a faster and/or higher quality answer.

[loverdos]

Just in case someone is interested to dig further:

Real World Haskell and the Mercurial book used a web-based comment system.

http://www.realworldhaskell.org/blog/2008/02/10/about-our-comment-system/

http://hgbook.red-bean.com/

[d6y]

The hgbook suffers from the problem of having threads like "You should do X" followed by a "Thanks, added that" comment. I'd like to avoid those distractions for the reader if possible. I don't mind flagging unresolved comments in the text, as long as there's a way to resolved/remove the comment once it has been delt with.

[mads-hartmann]

I agree :) For now I think it's fine to add a link with mailto:liftweb@googlegroups.com with a subject something like "[Lift Cookbook] Your Subject"

[d6y]

To try this out, I've put a link at the end of this one:

http://cookbook.liftweb.net/Access+restriction+by+HTTP+header.html

[pr1001]

Unfortunately the pluses are not converted to spaces for me. Not sure if it's Chrome or Mail.app...

[d6y]

Ah, right - thank you for letting me know. I'll dig around and try to find out what I should be doing. Must be an RFC for this. Somewhere.

[pr1001]

Try %20 instead?

[d6y]

Attempt 2! Now with %20 goodness: http://cookbook.liftweb.net/Access+restriction+by+HTTP+header.html

[pr1001]

Works on the iPhone!

[mads-hartmann]

Work in safari :)

[d6y]

Great - thank you. Next up: figuring out a way to automated that footer on each page. Pamflet hacking or maybe just a bit of sed/grep/awk voodoo.

[mads-hartmann]

Pamflet hacking would be idea IMO but that depends on how much time you want to spend on it ;)

[mads-hartmann]

Closing this so it doesn't show up in my Github list of issues :)