A (really) simple commenting system for HTML wireframes

A new year brought new contracting opportunities and, again, I’ve been working remotely for the majority of it.

The company I’ve just finished working for, Safari Books, have a lot of remote workers and collaboration tools around deliverables (for example commenting on Google Docs, or HipChat) are key to making this work.

For flat wireframes or designs, this is straightforward – upload PNGs or JPEGs to Google Docs and take advantage of the commenting system. For HTML prototypes, it’s not so easy.

A fairly fruitless search

After a fair bit of Googling, and a conversation with Craig Melbourne, I came across ProtoNotes which essentially attaches post it notes to any web page. This seemed to be the closest thing to a commenting layer out there. However it wasn’t what I wanted, which was something closer to Google Docs implementation.

For my first deliverable, with time at a premium, I used ProtoNotes and quickly ran into problems with whole notes disappearing, or comments within notes not being saved. Clearly that was unsustainable as a long term solution.

Another side project

As I mentioned earlier, my idea was basically the same as Google Docs – comment on any element.

Metaframe, the project I forked to create loznotes, has introduced general commenting in the notation tab, but I wanted something that could stand alone outside of notations.

Commenting on any element would require a method of storing unique identifier against each DOM element, plus a means of keeping track of that when the page is updated and new elements are added.

Frankly, I’m not that clever.

Craig advised me to scale back my ambitions a little bit and over lunch we came to the conclusion that focusing on comments at a less granular level, say containing elements, was doable. ‘Commentable’ elements would have data attributes on them to hook the jQuery to, in a similar way to loznotes.

It would still require some way of storing comments, but I thought I could get a version out of the door fairly quickly. Craig had been using Firebase in some of his UX work, and suggested that would work well.

A night of messing around left me with a working proof of concept, with some formatting issues to sort out. Another day or so of tinkering and I had a version 0.1.

Introducing lozcomments

And thus the third of my egotistically title loztools was born: lozcomments. You can view it on GitHub, or try the demo.

The way it works is fairly simple. In your markup, you add a ‘data-comments’ attribute to any element you require commenting to be enabled on. The actual data in the attribute must be unique, and take the format of “comment-[x]”, where “[x]” is a number of your choice.

In the Firebase, a node is created using the page title attribute, and each comment thread is created as a child of this.

Individual comments will accept basic HTML (including, as Keith Fahlgren so ably demonstrates on the demo page, the marquee tag). Links, both with and without ‘http://’, are possible and link correctly, and ‘@’ mentions are also highlighted (though a little bit superfluously right now as there is no automatic notification).

It’s now version 0.2 as of this writing and it’s still a little rough around the edges, but it’s a very (very) simple, usable, commenting system for HTML wireframes and design mockups.

It’s not perfect by any means, and there’s some limitations with it, but it works.

Issues

In usage so far, aside from CSS z-index problems, I’ve found that:

• most people actually comment on things with notes¹;
• despite the above, one of the first questions people asked was, ‘how do I comment on an element that doesn’t have a speech bubble/note icon next to it?’;
• keeping track of elements with the data attribute on them – even when they are only on high level elements – is a pain, especially when includes are involved;
• and finally, staying up to date with threads involves checking each individually as there is no notification system, or way of viewing all threads together.

Given some of the above, I’m considering moving away from threads displayed by elements and more towards a pane, like loznotes. I also need to think more around how I can solve the issue of keeping track of elements that have the ‘data-comments’ attribute.

Clearly it needs more work and I’m also investigating ways to move closer to my original goal of commenting on any element. For now, though, I’m quite excited to have a third project on GitHub and something to pour some extra curricular energy into.