Page MenuHomePhabricator

Support commenting on Phriction documents
Closed, ResolvedPublic

Assigned To
Authored By
Oct 12 2012, 8:55 PM
Referenced Files
"Like" token, awarded by kerberizer."Like" token, awarded by ekubischta."Like" token, awarded by zcourts."Love" token, awarded by timor."Like" token, awarded by dnulu.


Top-Level Comments: These are easy to add technically, but I'm concerned that old comments will quickly become stale/irrelevant because many wiki pages are very long-lived relative to other types of content. (For example, the comment section of most PHP documentation pages has a bunch of comments from 1993.) There isn't an obvious way to make sure only relevant/recent comments are shown or to deal with toplevel pages gradually becoming overgrown with discussion.

Possibly we could literally show recent comments, or show comments against the current version of the page, wiping the slate clean after an update. Or we could just let page editors hide comments.

Inline Comments: These are difficult/pretty-much-impossible to add technically in the way that Quip/Paper/Google Docs/Word work because we do not have a WYSIWYG editor and only see old and new versions of pages, not sequences of edits against a page. When an inline comment is on a sentence and the document is reorganized and the sentence is rewritten, we often can not reasonably keep track of it without seeing that sequence of individual mutations. Docs/Word/etc can because they see the move and rewrite as separate operations, and can keep the comment in the correct place across each small mutation.

We could accept this and try anyway, but I suspect the results would be very poor.

It's vaguely possible we could use a bunch of Javascript to try to capture the path that an edit takes and then submit it alongside the new text to track inlines, like Docs/Word do, but without implementing WYSIWYG. I suspect this would still be very complicated.

We could record inlines against static text -- for example, against a specific version of a wiki document, or a specific change to a document. Perhaps this would be good enough.

We could support inlines in the actual document text through an {!inline ...} sort of syntax, although I think this is so kludgy that I'm not inclined to pursue it. I think this can (mostly?) be implemented as an extension anyway.

With top-level comments, we could provide a way to quickly quote a sentence or paragraph (say: hold shift, move cursor over paragraph/sentence, click, get quote block in comment textarea -- or long-press on mobile or something). This wouldn't be an inline, per se, but might be good enough.

Event Timeline

giancaldo raised the priority of this task from Normal to High.
epriestley raised the priority of this task from High to Needs Triage.Oct 19 2012, 4:13 PM
epriestley added a subscriber: epriestley.
epriestley triaged this task as Wishlist priority.Oct 19 2012, 5:13 PM

(That guy was really excited about reprioritizing tasks.)

This feature seems like it would be nice to have, but I'm worried that implementing it would be very challenging technically.

Phriction documents aren't line-oriented, so we can't attach comments to lines in the same way we do in Differential. Two ways I could imagine the UI working:

  1. You select some text with your cursor, and we pop up a dialog box for you to add a comment about it.
  2. You mouse over the document and various "atoms" (sentences, paragraphs) highlight and you can attach a comment to them.

I think both of these would be really messy. In (1) we'd need to derive the document position from information the browser gives us, which is likely to be difficult (there are a lot of quirks already with the limited selection stuff we're doing for copy/paste, e.g.). In (2) we need to split arbitrary language into sentences, which seems very difficult for non-latin languages. These would both be fairly fragile to changes and difficult to port across document versions.

We could do more low-tech solutions:

  1. Add a Remarkup syntax for adding a comment, like {! ... }. Then you edit the document and add {! This is confusing, can you clarify? -epriestley} or whatever. This is technically very easy but probably not so hot from a UI perspective. I think this is how Wikipedia works though, so maybe it's viable?
  2. Add non-inline comments and maybe just give you some easy UI to put quote syntax in them?

What sort of use cases do you have for this? Would either of the low-tech approaches be reasonable?

Some potential overlap with T337: Add a Rich Text editor to Phriction but that's not going to happen too soon.

Cobi attached 1 file(s): Restricted File.Oct 19 2012, 6:54 PM

Low-tech #1 would work well for us.

Other improvements that could be done:

  • auto-signing/dating with the {! ...} syntax
  • the ability to select whether to hide or show the comments at the top of the document
    • The ability to select between a full comment box, a simple inline (@Cobi: Message goes here) type comment, and perhaps just an indicator that a comment exists there that could be clicked to expand into a full comment box.
  • The full comment box should probably have a reply text-box so a reply to a comment can be done quickly without having to go into the remarkup.

I've attached a quick mockup of a full comment box in a phriction document.

Agree with @Cobi, this would be something our engineering & product team could really use. Ideally, the inline comments should not distract from the document. This will make wiki more subtable to collaboration and commenting. Thanks for considering.

I had an idea. We could do two versions of this, one for Frontend editing and one for document editing.

The frontend part looks exactly like Differentials' inline comments. Instead of attaching to a line we attach to a human-readable anchor though. An anchor in the document looks something like {!#comment-3 | Preview: Text is unclear, please ela... | Added 3rd Feb 2013 by @AnhNhan}. We then insert the comment like @Cobi mocked it up nicely during formatting. This way comments may be tracked in position across edits, and can be deleted by future authors, and also nicely linked (similar to D5395#inline-6128). We can probably tolerate change to some degree, recognize the anchors only by {!#comment-(?P<id>\d)(.*?)?}, the rest being for readability

Document editors, well, they use the Remarkup syntax described above. Linking may be a problem for these though, since they are not identifyable. Convert them to anchors like above?

I would make the comments a little bit more light-weight though, small floating containers on the right side for example.

Maybe also add some style variants, red blue and green ones.

can we have some kind of basic support for this please ?

We don't need inline comments. The ability to add comments to the end (like with this Task) would work for us.

inline-comment is really a good feature to have.

How about add normal comments first? Allows other users (with or without edit access) leave comments below the wiki content.

+1 for just adding normal comments at the foot of the page, below the main document content.

chad changed the visibility from "All Users" to "Public (No Login Required)".
chad added subscribers: rhkeeler, jhurwitz, angie.
angie added a project: Restricted Project.Oct 26 2015, 9:28 PM
epriestley renamed this task from Phriction inline comments to Support commenting (top-level and/or inline) on Phriction documents.Jun 7 2016, 1:04 AM
epriestley added a subscriber: hach-que.
eadler added a project: Restricted Project.Jun 7 2016, 1:47 AM
eadler moved this task from Restricted Project Column to Restricted Project Column on the Restricted Project board.Jun 7 2016, 6:19 PM
eadler moved this task from Restricted Project Column to Restricted Project Column on the Restricted Project board.Jul 4 2016, 9:00 PM
chad renamed this task from Support commenting (top-level and/or inline) on Phriction documents to Support commenting on Phriction documents.Aug 8 2016, 9:18 PM
chad moved this task from Backlog to Next on the Phriction board.
chad added a parent task: T9379: Build Phriction v3.

I've taken a pass at this in the design on Phriction v3, and it's top level comments only. The comment pane by default is hidden, but expandable. You can see comments on previous versions, and pull them up separately. I think this is a reasonable place to start over inline commenting and trying to recreate Dropbox/Quip/Google Docs, etc.

Also, re:

It's vaguely possible we could use a bunch of Javascript to try to capture the path that an edit takes and then submit it alongside the new text to track inlines, like Docs/Word do, but without implementing WYSIWYG. I suspect this would still be very complicated.

This also wouldn't work when people edit the Remarkup in another editor and just paste it into the comment box, as I do (usually via the Firefox It's All Text extension).

Consequently, I think top-level comments only makes a lot of sense technically. A quote facility to accompany it would be great.

I'm not sure how attaching comments to particular versions will work. I realise you're trying to avoid the stale comment problem. In our workflow, we often address comments in multiple updates, and of course this would make them disappear after the first update. That said, we can always keep doing what we do already and discuss in an accompanying Maniphest task. So offering something different in Phriction could be wise, as it will catch other use cases.

Did you check out the mock in Pholio?

No! I hadn't noticed it, sorry. I've had a look now and will endeavour to give some specific comments over there later. I don't think the 'addressing comments in multiple updates' will be a problem, though.

There's a separate task floating around for making Phirction changes reviewable. I think that should be separate from this task to keep things lightweight.

Jira's Confluence provides inline comments; same model could be used by Phriction. But that's not as important. Should at least have support for end-of-doc (footer) style commenting.