In this tutorial series, we walk through the process of creation of our per-paragraph commenting app using Django as our backend, with Javascript and jQuery (ajax) for the front end. In this first tutorial, we discuss various issues and possible solutions of solving this problem of per-paragraph commenting.

I like how the comments look like on Medium.com. I am a compulsive scribbler when it comes to the corners and margins of hard-copies and THAT is something I dearly miss in e-reading, other than the comfort of reading from a book compared to a radiating screen. When I first saw this commenting style on Medium, I liked it right away. That was the time when I had no idea that I’d be doing web development at all (I didn’t know web development).

Image Credits

While the efficacy of such ‘notes’ on web articles is a long debated topic with Medium.com Website standing as a colossal corroboration of ‘it works!’, the arguments blared by horns of the opposing pavillion are just as sound! Notes have their place, but they cannot exactly replace comments. Buuut, they do make the articles personal! For it is totally up to you to comment on one particular paragraph, or a selection of lines, and not on the entire piece. Also, not everyone reads the neatly folded annotations. So, where do they work, and where do they not?

An annotation that is longer than the post itself does not work. For that (if you really intend to do so), we have comments. Plus, if we can control the privacy of annotations, they can really benefit as notes scribbled on a personal book while helping preserve the context of the thought. As a result, I’d want to make one for our project, and now have a working prototype on which you must be reading the post.

I’ll admit that the inspiration is the Medium.com website while the various options of how to go about the problem were evaluated from this post on StackOverflow. Then, I found this little project ‘Sidecomments.js’ which had a replica of Medium-like commenting system. I tried to use it (since I barely knew JS or jQuery back then) and when it did not work (since it needed Require.js, and perhaps Node.js), I pulled up my sleeves for making one myself in vanilla JS (in a bid to learn JS) and well, for the fun of it.

So, this is what we would like to make:

1. A notes app that allows us to make comments, hereafter referred to as Annotations, on article content, then and there.
2. Allows the user to tune its privacy, allowing them to make it public, private, visible to self and author, and to a user entered list of friends.

There are certain concerns that this evokes:

1. How do we identify what comments were made on what paragraph?
2. What if that paragraph or content is deleted?
3. What if the author of the article wants to respond but only let the author of annotation know?

So, here is how we answered them:

How do we identify what comments were made on what paragraph?

We developed an engine in our content app, which assigns unique IDs to each content type on which annotations can be created by the user before it is saved to the database. For every article, these IDs usually start from 1. The obvious limitation being that the we cannot have annotations on a page where more than one content entry is being displayed. I think that is okay, for annotations on blurb listing pages would be absurd for me. Anytime the content gets updated, the previous IDs remain intact (unless the content is deleted, of course). Even in the event of content deletion, the ID is never reused (it is a linear list which constantly increments). The annotations are saved with keys to their article and its paragraph ID.

What if that paragraph or content is deleted?

The answer lies not in how we save annotations, but in how we display it. Annotations are displayed in two places on a page. One is where they belong, on the margins of the text. Next, they are also collected down in a separate tab adjacent to the comments tab. If there are some orphaned annotations, you can find them in this annotation bucket. Plus, if you want to treat them as regular comments, so be it, they are here, at the bottom of the page.

What if the author of the article wants to respond but only let the author of annotation know?

Since we’ve already proposed that we’d want to maximize tunability of privacy in our projects, scalability of such flexibility is paramount. But we have to make tradeoffs to make something work, and since we value your privacy more than anything, we’ve found our answer in dealing with this problem outside the context of annotations. But to understand the rationale of our solution, you’ll have to understand what annotations mean to us.

Annotations are personal interjections, or ponderings that happen while reading an article.

Annotations are personal interjections, or ponderings that happen while reading an article. They are not exactly debatable, but can be a short feedback of sorts to authors, something said by a person to a person, and not broadcasted to everyone. You could think of them as review comments before they are published, the usual reviewing stuff that goes around while content writing. The problem here is, not one, but many people will make such annotations.

Thus, annotations that are aimed at starting conversations must result in conversations. However, they mustn’t do so on the post, but in the privacy of message boxes. Say, a person made a public annotation on an article, and somebody wanted to respond to it. He can respond to it via a message. This is possible rather easily because the other person too is a member (since annotations are for signed up users only). This can lead to great friendships and establishing novel social study circles while keeping the article relatively clean of the informal chatter that might then take place. The concept of group messaging shall allow more people to join in the conversation should the two (original people in conversation) oblige unanimously. Unanimous voting in favor is required because even one person who does not oblige will be offended, and if that is so, we have a problem.

[Also know that all of these are pipelined. So, Friendship circles, as of now does not exist on our portal (we’re on our way though!). Thus, you could think of this requirement as a part of a bigger charter, and only the relevant parts would be implemented for now. But rest assured, as and when the segments are added to the portal, the tutorials will also be updated.]

So, let us begin with creating our app from the next tutorial