Instructions for Using Diigo to Comment on Documentation

[Silas]

Mobicents Users and Developers,

To be on the bleeding edge of collaborative documentation editing,
you'll want to check out Diigo, which is a combination bookmark-applet
(more about this below), a browser extension (for Firefox, Flock and
IE), and which can bookmark and annotate web sites for the public and
groups that you can define. Diigo is an acronym (it should properly be
DIIGO) for “Digest of Internet Information, Groups and Other stuff.”
It has a lot of Web 2.0 features, and is a competitor to del.icio.us
for social bookmarking.

I want to try using Diigo simply for easy commenting on the User Guide
and possibly other documentation. Diigo provides page comments, sticky
notes, text highlights and a lot more, through the bookmark-applet, a
browser extension and its sidebar. If you install the Diigo plugin,
create an account on diigo.com and login, you can then see other Diigo
users' comments on any web page you visit. Or you can log out and not
see them. I've uploaded a screenshot of the User Guide with various
notes, highlights and annotations that I've made, so that you can see
what it looks like in action. It is actually quite impressive. Here is
a humungous, indirect link:

http://mobicents-public.googlegroups.com/web/diigo_srceenshot.png?gda=5PK9xEUAAABnhsWSPth9NOzmlzE67TrluMB3ygkKjJr7CuPHMP7WzGG1qiJ7UbTIup-M2XPURDRfwELsWLHgeSz6UL8EgTVfdpYBJ5BE1MkfeEWZwx82kQ&gsc=a_cslgsAAAAZVXQmnJy0ukIGXLci9L28

Also, I've created a Diigo group called "Mobicents Documentation",
though I can't find it through searching for it, at least not yet.
This group has a forum with email, a list of shared bookmarks, and--
best of all--fine-grained permissions for adding members, showing your
annotations to others, etc. It appears to be modeled on Google Groups,
though with somewhat different functionality.

HOW TO GET STARTED
Although Diigo is available for Fireflox, Flock and IE, I am using
Firefox 2.0 in the directions below.

1. Go to http://www.diigo.com/sign-up
2. Enter some information and hit "continue". WARNING: I told Diigo
*not* to access my Gmail address book, and add my addresses to my
Diigo profile. Diigo will ask for your GMail password, which I think
is an insecure and improper thing to do, though convenient (and Diigo
knows it, and I am betting that most people could care less). I do
care about security, however, and limiting access to personal
information. Diigo works just fine, if not quite as conveniently,
without access to your address book.
3. Head to http://www.diigo.com/tools/diigolet and add the "Diigolet
super-bookmarklet" to your bookmarks. For various reasons, at least on
Firefox, Diigolet is preferred over using the toolbar, which is
optional. You can, of course, install both, and it is suggested.
However, they have different capabilities. Most importantly, I have
had trouble using the (Firefox) toolbar to create *Public* floating
sticky note comments, so I simply use Diigolet for this. However, this
problem will probably be resolved, perhaps once more of you sign up
for Diigo and add each of us as Friends.
4. (Optional but suggested) Go to http://www.diigo.com/tools and
install the diigo toolbar in Firefox, Flock or IE.
5. Sign in to Diigo, if you are not signed-in already, by doing the
following in either Diigolet or the Diigo toolbar.
a) Diigolet: click the "Sign-in" button.
b) Diigo toolbar: click the "Diigo" dropdown (you might have to
enable the toolbar in your browser for it to be shown)
5. Open the Diigo sidebar (Firefox and Flock terminology--not sure
what IE calls it)
6. Go to http://groups.google.com/group/mobicents-public/web/chapter-Introduction.html
and you should see a Page Comment in the sidebar and a Floating Sticky
Note on the page, both of which I created.
7. Go to the User Guide portal page (i.e. the Table of Contents),
located at http://groups.google.com/group/mobicents-public/web/user-guide
, and start commenting! It is highly advised to leave "Public"
comments. At this point, it would help to read the two sections below,
about the mechanics of sticky notes and best practices for Diigo,
before commenting heavily.
8. Finally, email me and tell me you've got Diigo installed, and I'll
make you a member of the Mobicents Documentation group. I've
configured it so that you can then invite and add others without
having to go through me.

MECHANICS OF STICKY NOTES
Naturally, I will be updating the User Guide page on Google Groups,
which leads us to ask the question: "What happens to people's sticky
note comments after the page has been updated?" The good news is that
Diigo's mechanics will work well for us, and here's how:
* text that was highlighted in the previous version remains
highlighted after an update. ← * Page Comments and floating sticky
notes both remain.
* Text that had been highlighted and then changed in the update will
remove the highlighting, which shouldn't be a big deal (simply always
leave a short note attached to highlights).
* Finally, sticky notes attached to highlighted text which changes
(thus removing the highlighting) will *not* delete the note; instead--
and properly--those previously-attached notes simply become floating
sticky notes. The side benefit of this mechanic is that floating
sticky notes that have become unattached from their highlights due to
a page update remain listed with all their text in the sidebar but
won't appear in the new page because they don't apply to the new text.
Thus there is a way to discriminate more-or-less easily between
previous, historical comments and new, applicable and relevant ones.

BEST PRACTICES
Note that I wrote this section before experiencing some trickiness
with getting Public floating sticky notes and Public highlights to
work. I think these will become best practices, once some kinks are
worked out, and once a number of people have joined Diigo and added
each other to their "Friends."

My recommended best practices for using Diigo to comment documentation
are:
→ Use simple highlighting (without a note) only for minor spelling
errors (if you can find them ;-)
→ Otherwise, always select the text you want to comment on, click the
arrow next to "Highlight" in the toolbar, and select "Highlight and
Comment". Tip: you can also right-click to bring up the context menu
in Firefox and select "Highlight". Then click on the highlight to show
the "Add sticky note" and "Delete" options.
→ Insert floating sticky notes, which are unattached to any
highlighting, by going to Comment on the toolbar and selecting "Add a
floating sticky note to this page". Don't forget to drag its cartoon
bubble to the relevant paragraph or section after you've hit "OK".
→ Page comments should only be used to talk about the entire User
Guide or a process or something similar; they should not refer to
specific sections (use a floating sticky note for that).
→ Delete your old and inapplicable comments. I only dream of reaching
the point where there are too many comments and notes on the User
Guide page, and editors should start deleting their unattached or
irrelevant comments...
→ Have fun! Digo's a blast. And tell me about any cool new
functionality you find ;-)