create new tag
, view all tags

Brief: Improved Support for Annotation and Reviews

Problem Statement

I am evangelizing wiki to a community that is more used to emailing Microsoft Word and PDF documents around, adding reviewer comments to the document using those tools' annotation modes.

Of course, they can do this in wiki... except that the annotation modes have several features that are easier to use that annotating a wiki document:

  1. In a wiki document, you have to hit edit, and navigate to where you want the annotation to be. Whereas in Word or PDF, you just click, and annotate at exactly the point you want.
  2. Word and PDF automatically make each reviewers' annotations a different color, marked with date, reviewer, etc.
    • My users particularly miss colored annotations. Of course, in wiki you can add color to your annotations - but you have to do it by hand.

Overall, wiki editing is more suited to

  1. collaboratively editing a document b. or, appending comments to the end of a page
Wiki editing is not suited to detailed reviewing.

CommentPlugin helps, but, again, is more oriented towards comments at the bottom of a document.


Perhaps a token - like a small red dot - could be added besides all paragraphs. If the user clicked this, they would be presented a text box in which they could tyupe their comments. A unique color could be created for each reviewer; date and time info could be automatically generated.

-- AndyGlew - 18 Mar 2006


Every paragraph/bullet/table in the PurpleWiki has an anchor / can be linked to. This could be extended with an annotation feature as you describe. There are technical details to solve, such as if to store annotations with the text or out-of-band. The latter one has a challenge on how to associate annotations with a paragraph. Pargraphs are moved around in the topic, and paragraph content changes.

The annotated text could be toggled on/off with a twisty feature, individually, or all on a topic. For printout there should be an option (with URL param) to show/hide the annotations.

This feature would be a big win for TWiki, it is very much in line with the TWikiMission.

-- PeterThoeny - 18 Mar 2006

I've been working on this on and off, and was intending on using a branch and merge mechanism, with a popup UI similar to MSWord's - probably utilising annotea's (sp?) annotation server concepts - so that its even standards compatible...

-- SvenDowideit - 19 Mar 2006

Another candicate for using AJAX to give a smooth user experience.

-- PeterThoeny - 19 Mar 2006

This would be nice to have. See http://www.mystickies.com/ (also has Firefox extension).

-- MarcusLeonard - 19 Mar 2006

See my commments on May 2005 on CommentPluginDev and SectionalEditPluginDev (also in the Feature Request table on the later) regarding this exact feature. It is something that I've been wishing for a long time but haven't had any bandwidth to tackle.

-- PankajPant - 20 Mar 2006

AJAX would be the nicest way, allowing annotations at an arbitrary point - e.g. right click, pull down the annotate menu.

However, I think this is mainly a user interface issue. The first thing to do is to enable arbitrary annotations at arbitrary points.

Here's an example of what might need to be done: let's assume that the annotations are inline (which I think is probably easiest, and most wikilike). If the annotation contains a blank line, then it will interrupt things like list numbering. To avoid such interruptions, we might need something like a <saveenvironment> </saveenvironment> pair, to, umm, save the list numbering environment.

-- AndyGlew - 20 Mar 2006

If stored with the text it can be simple stored at the end of each paragraph, like this example:

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.%ANNOTATE{Good points here.%0APossibly add...%0A%0A--Main.AndyGlew - 20 Mar 2006}%

Newlines can be encoded to keep everything on the same paragraph. That would allow also annotations in table cells. Storing annotations with the text using variables is a wiki-like; annotations can also be removed/changed in edit mode. Nevertheless it is somewhat geekish.

An icon indicates the state of the annotation:

  • annotate_open1.gif - open box to create new annotation
  • annotate_open2.gif - open box to show existing annotation
  • annotate_close.gif - close annotation box

An annotation box can be shown with a JavaScript windows. Example:

Ideally, with in-place editing, and saving content back via AJAX.

-- PeterThoeny - 21 Mar 2006

My users almost never use the annotation box features of Word (although they use those features in PDF, where there is no choice).

More often, they just want their text to appear inline, but colored differently, dated, optionally indented.

Heck - I have seen Word documents where entire chapters are in the annotations. I.e. don't just assume that annotations are short.

I think this suggests that something like the following is better:

    Lorem ipsum dolor sit amet, consectetur adipisicing elit, 
    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris 
    nisi ut aliquip ex ea commodo consequat.
      Good points here. Possibly add... --Main.AndyGlew 

Giving output like:

    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
      Good points here. Possibly add... --Main.AndyGlew

In fact, when I "simulate" annotations myself, I nearly always do it via <UL> and <font> directives. Although I have to be careful not to break TWiki list numbering when I do this.

I.e. I'm suggesting something simple, automating what people already do in Wiki, rather than something new. A link at the end of each paragraph that inserted the above would be fine.

-- AndyGlew - 22 Mar 2006

Need a good solution for this problem.
And we have one smile
This should automatically add a sig, like CommentPlugin.
AG: cool. I had not realized it was implemented here.

How about something like this? Essentially, a small EditTable that can be used to add/edit notes. If we have an automatic way to add them to all headings (depth selectable), it would probably suffice. Most of the time, annotations don't need to be right next to a specific paragraph. Think about a using bookmark when reading a real book ... it indicates the page that you stopped at, not the exact paragraph or sentence.

-- PankajPant - 13 Apr 2006

Could the automatic positioning be derived from SectionalEditPlugin? It has an edit link to every paragraph (depth scalable)

By the way, it would be really cool if there would also be a mechanism for:

  • showing / hinding all comments
  • change the color of the cell based on the reviewer
  • be able to remove comments once they're dealt with - all under revision control

-- JosMaccabiani - 13 Apr 2006

I think Pankaj's suggestion would be a great first step.

But I disagree - I think ultimately it wants to be per paragraph. Per paragraph would probably be okay, but in my group at Intel people always enter stuff (in a different color) inside sentences!

-- AndyGlew - 14 Apr 2006

WillNorris says that my last comment doesn't make sense. I think it does - what is unclear aboutr:

I think that it does. What is unclear?

a) Per heading annotations would be a good start.

b) But per paragraph annotations would be better.

c) However, the people I work with often do annotations - really, suggested extensions - inside sentences:

ORIGINAL: Here is the first sentence. Here is sentence two.

ANNOTATED: Here is the first sentence [AG: and clause 1.1, and clause 1.2]. Here is sentence two.

Why do people do this? I think that it is because we are writing complex specs. It is too hard to say "in the 4th sentence, at the 3rd comma" - it is just easier to add it in-line.

Yes, there are really two different classes of annotation: inline stuff like the above, and out-lying stuff such as PeterThoeny suggested - like PostIt notes. In my world, the inline stuff predominates. Word has the ability to do the outlying postit note type stuff, and it is almost never used.

-- AndyGlew - 17 Apr 2006

"I think ultimately it wants to be per paragraph. Per paragraph would probably be okay..." - that bit doesn't parse.

-- WillNorris - 17 Apr 2006

Let's distinguish between Word's "comments" and "track changes". The first is for reviewing, the second for collaborative authoring. Theoretically, because also in my workplace the uses are mixed, with most people using track changes since it was available longer. For the comments, the solution by PankajPant looks very promising, when combined with some mode to show/hide all and individual comments.

Actually, the track changes is used better when someone has more detailed comments, as AndyGlew already showed. But trach changes is almost wiki editing, except that there is a workflow where the contributions are colored and indentified, deletions are striked and someone has the option to 'merge' them into the final document without to coloring. I'm not a coder, but can't we already do that somehow?

-- JosMaccabiani - 17 Apr 2006

Could someone (Arthur/Harald?) who is familiar with Ajax sketch out a possible implementation? I'm not familiar with Ajax at all, but am prepared to learn and try some things out. One thing that I'm confused about is where should the annotations go: inlined in TML, metadata or a separate file?

-- PankajPant - 15 Jul 2006

I meant to add that I've tried to comprehend the stuff in TWikiAjaxFramework but remain completely clueless about how to go about starting something like this.

-- PankajPant - 15 Jul 2006

I just came across a new site: http://www.diggo.com. The cool thing is the "sticky-note" feature. You can simply highlight some text, right click and add a note. The next time you are at the page, the note shows up. You can make it "public" so that others see it too. Try it out at their playground.

That's what we want from AnnotationPlugin. Could someone outline a potential solution? I'd be willing to tinker and see if I can come up with something.

-- PankajPant - 03 Aug 2006

I just gave diggo a spin. Easy to use, nice UI. Who is coding up a TWiki Plugin with this functionality?

-- PeterThoeny - 03 Aug 2006

The diigo UI itself wouldn't be that difficult. I've played around with it in the past few days. The one hurdle I'm trying to overcome is - How to save the modified DOM to disk on the system?

-- SteveHajducko - 05 Dec 2007

The TWiki API has functions to read and save topics. You could save annotations embedded in TWiki topics, or attached as custom meta data. See docs at TWikiPlugins and TWikiMetaData.

-- PeterThoeny - 06 Dec 2007

Saving the annotation itself isn't difficult. The difficult part is saving the point in the document where the text that was annotated is, if we're trying to implement an AJAXian interface similar to that of diigo.

One solution would be to create a range object and save the coordinates of the range as metadata. When someone loads the page, the ranges would be recreated. The problem then is that if the document gets modified, the annotations would break, since the range coord's would now point at the wrong text.

We also just can't take all the text from a specific node and save it to disk, as it would then overwrite all the TWiki formatting in the document, along with all the meta data. Also, doing a regexp search based on the highlighted text would work, but would give false positives ( if someone annotated the word 'the', then every 'the' would come up as being annotated ).

I'm up for suggestions on how one would save a select object back into the metadata of the TWiki doc itself with ajax, it's the one thing I cannot figure out.

-- SteveHajducko - 06 Dec 2007

One possible leverage point is TWiki's TOC system. That is, use section headings to limit the range where annotations would be linked. In LaTeX, the cross-links between text are handled by labels, with the label stored as Section-Subsection-Subsubsection-paragraph. This emulates the range object mentioned above, and may make a useful range mapping. For your example of annotating a word 'the', the location could be marked by "Section-subsection-subsubsection-paragraph-Nth_'the''. I use this just as an example. It may make more sense to link the annotation to the start or end of a sentence, e.g. "Section-subsection-subsubsection-paragraph-sentence_start_with:'For score and seven years'''.

Also, I suggest having the range/label associated with a specific rev of the topic. Then, if the topic is modified on the server by one editor while a second is adding annotations, the annotation location wouldn't be lost. On 'annotation save' the object would post the location based on the topic rev on which the annotation was created. If the topic rev has increased, then do a search in the new rev using a (reasonably large) block of text from the annotated rev and find the new location. It may make sense to alert the annotator of the change, to confirm the new location is correct.

I look forward to seeing this feature introduced. smile A number of my wiki users would jump at the chance to use it.

-- ScottHoge - 07 Dec 2007

I would implement it the way I stated on 21 Mar 2006: Annotate per paragraph/bullet/table cell, at the end of the element with an %ANNOTATE{}% variable. This does not affect the TML rendering (such as a bolded bullet), and it survives refactoring. It reduces the risk of broken annotations compared to using labels and links.

-- PeterThoeny - 07 Dec 2007

My needs are more how we go from the modified DOM in the browser to actually inserting the %ANNOTATE% tags into the text file on the server, using AJAX.

For instance, if we enable a select object and create a range out of it, we can modify the DOM that is displayed, but how do we translate that modified DOM back into the saved text file on the system, while matching the correct place in the text document?

An example:

Displayed HTML/DOM:

<p>This is a <b>test</b> of the <a href="WebHome">Emergency Broadcast</a> system.</p>

If the user selects "a test of the Emergency" and annotates that, how do we properly place the %ANNOTATE% tags in the text file on the system, when the text file looks like this:

This is a *test* of the [[WebHome][Emergency Broadcast]] system.

An easy solution this would just to make the user required to edit the page and insert %ANNOTATE% tags around the text manually, but doing this via an AJAX interface, where we really only have access to the DOM, adds some complexity.

A good article about the difficulty in finding the actual insertion point via AJAX is described here. TWiki adds a bit more complexity because the data is stored in a different format than what is actually displayed, which is why I'd consider storing the range objects via meta data and then recreating the selections during rendering.

-- SteveHajducko - 07 Dec 2007

Indeed, the mapping from DOM to TWiki can be difficult. You can avoid the complexity if you limit the annotation to one paragraph by adding an icon at the end of each paragraph. annotate_open1.gif

  • Same for bullets annotate_open1.gif
  • One annotation per bullet annotate_open1.gif

And for table cells annotate_open1.gif and heading cells annotate_open1.gif
Like this annotate_open1.gif and that annotate_open1.gif

These icons would be linked. Clicking on one opens a small window to annotate the paragraph. The save action would initiate a REST call to save the annotation text in place. Only paragraphs with annotation have an %ANNOTATE{}% variable, other paragraphs only show an icon at rendering time to give a visual clue that one can put an annotation to this paragraph. The icon could be done a bit less intrusive. annotate_open1.gif

-- PeterThoeny - 07 Dec 2007 annotate_open1.gif

You might want to look at MetaDataDrivenTagDesign for some inspiration.

-- PankajPant - 08 Dec 2007

That one talks about annotation while in edit mode. This here is quicker; annotation in view mode.

-- PeterThoeny - 09 Dec 2007

Edit | Attach | Watch | Print version | History: r33 < r32 < r31 < r30 < r29 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r33 - 2007-12-09 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.