Making website feedback easy

The last few days I've been working with my wonderful documentation guru, Sheena, to streamline the process of creating and contributing to SDL documentation.  We needed a way for people who want to contribute to the documentation effort to share information and coordinate their efforts.  We also wanted to make it extremely easy for people using the documentation to suggest improvements or request clarification.  We're using a wiki, but have locked down permissions to avoid the plague of spammers that abound on the Internet today.

Creating a way for active contributors to coordinate was easy.  We're hosted on Dreamhost, and they make it painless to set up a new mailing list, so we redirected docs@libsdl.org to a new mailing list for contributors.

Creating a way for casual readers to contribute and give feedback was more difficult, especially since I wanted to make giving feedback inviting but not require Sheena to add markup to each page.  I wanted to make it possible to give feedback without following a link to another page, so the person would have the context of the page they were on for giving great feedback.  I also wanted to make sure that it was obvious how to give feedback, but also didn't interfere with the page content.

With these requirements in mind, I set off in search of the perfect feedback system!  After a short search, I found something that looked pretty promising:
http://tutorialzine.com/2010/09/quick-feedback-form-php-jquery/

It was pretty much self contained, which was a plus in terms of integrating it into the wiki site, and did a good job at being accessible without keeping an entire form on screen.  However once we added it to one of the wiki pages, a few problems became immediately apparent.  First, the color and general style didn't match that of the documentation site.  That's not too bad, a little photoshop time and adjusting some of the CSS sizes and offsets, and we're done.  A bigger problem was that it was positioned at the lower right, continually obscured important information on the page.  We looked at a couple of ideas, but the one that really made sense was to put it in the upper right.  A little looking at the CSS and Javascript code, adjusting some offsets and flipping the arrow toggle state, and we're done!

... or so I thought.

It worked perfectly in my test file on Firefox, but when I opened it in Internet Explorer it was complete garbage.  Not only was it not anchored in the upper right, but elements were badly overlapping and the button didn't animate anything.  To make matters worse, when I moved the feedback form from my test document to the real wiki page and viewed it in Firefox, the sliding panel was neatly anchored already out, instead of tucked up out of sight.

Okay, one problem at a time... first, what's the difference between the test file and the wiki page?  After putting some tests together and scrutinizing the page source, I realized that the wiki page had a <!DOCTYPE> element while my test page was hand coded HTML with no doctype.  It turns out that Firefox is smart and if a page specifies a certain flavor of markup in it's doctype, then it will be compliant to that standard.  If a page doesn't specify a doctype, then Firefox will enable quirk mode, which is essentially the combined experience of lots of web developers making pages work.  Now that I know that, it's just a matter of looking up the relevant section in the standard and fixing it right?

... of course not. :)

It turns out that the technique I was using, negative margin values, was perfectly acceptable and compliant.  After playing with it a bunch, I could never get the panel to move regardless of what margin values I used.  I shelved the problem and went back to Internet Explorer to see what I could do there.

<montage scene of me completely deconstructing the HTML and CSS and rebuilding it a piece at a time>

So after playing with it a lot, I realized that using headers and spans mixed with div markers was completely hosing Internet Explorer.  I carefully rebuilt the form using only <div> and images and after a few trials, voila!  It was anchored correctly, the sliding panel was initially out of sight, and then popped down into the correct location when I clicked the arrow.  I quickly switched back to Firefox and Safari and they were happy as clams.

Now that I had a working feedback form, I had to figure out how to integrate it seamlessly into the MoinMoin wiki.  I poked through lots of python code for generating the sidebar and implementing themes and found that someone had thoughtfully created a way to add custom markup to the footer of each page.  I just set the variable "page_footer1" in wikiconfig.py to the feedback form markup, and the feedback form was now on each page of the wiki.

For the final touch, I wanted the feedback to go to the documentation mailing list and include which page the feedback was coming from.  A few quick edits of submit.php and we are off and running!

You can see the final result in action at http://wiki.libsdl.org, and the code is available for your perusal at http://wiki.libsdl.org/feedback  Feel free to use it however you like, and let me know if you find a way to improve it!