Page MenuHomePhabricator

Provide a way to discuss content and changes of Phriction wiki pages
Closed, DuplicatePublic

Description

We use Phriction wiki pages as a place for storing our design documents for what we're working on. Unlike other parts of Phabricator, there's no comments or discussion section on wiki pages, which means if we want to discuss the content of a wiki page, it has to occur seperate from the content that's being discussed (through online chat systems like Conpherence). It's really hard then to have discussions about wiki page content if people aren't immediately available after it's written, because it has to happen in a place of conversation where the topic of conversation might change (as opposed to a comments section on the wiki article which is just focused on discussing that article).

It'd be really helpful to us to have a way of discussing the content of a Phriction wiki page in the context of that page, so that design decisions and conversations can happen around the actual content itself.

Event Timeline

I think this has come up a couple of times in the past, let me see if I can dig it up.

One concern I have about this is that wiki pages tend to be very long-lived compared to other content types and often never really get closed or cycle out, and if you look at something like PHP.net's documentation comment section it's fairly frequent that more than half the comments are woefully out of date / horribly wrong / whatever. I could imagine pages on this install like "Changelog" gradually collecting many pages of very temporary comments with no lasting value over their multi-year lifespan.

This isn't necessarily a real problem, but I'd be more comfortable pursuing commenting in Phriction if we had some ideas about how to mitigate it if it does become a problem, or how to structure the comments to resist it.

A (probably not great) idea is to tie comments to particular versions and wipe them when the page is changed, but I suspect that would be too disruptive to discussions in many cases.

I think a way of addressing the issue is to set the "There are 10 previous comments (show all)." bar that appears in transactions to at least comments that were made after the last change to the document.

For example, our plan for using Phriction in this way is to:

  • Discuss potential changes.
  • Make the changes.
  • Then record a comment from each person signing off on them.

Before the change is made, we want to see the discussion about the current content, so showing the comments made since this version was created makes sense. After we make the changes, we're just interested in whether everyone has signed off on it, so just seeing those comments for that version works as well. If we need to go back to discussion, we can click the link to show previous comments.

(Also, transactions for when the Phriction document was changed should also show up, so there'll be a clear delineation between the comments for different versions)

T3353 is the "Review changes in Phriction" task.

That task seems to be about reviewing structure of the document whereas we want to discuss ideas and content (and we don't need or want a formal review process).

Discuss potential changes.
Make the changes.
Then record a comment from each person signing off on them.

This is what you noted above, but this is not a formal review process?

We're not signing off on the textual or structural changes, we're just agreeing that the ideas expressed in the document are what we all understand them to be.

Like there's no point in that process where there's a draft document that's looked at. We just evaluate the new version and say, yeah that sounds good to me. But there's no reviewing of drafts like you would have with Differential (and we don't want that extra level of management / overhead).

And of course, this is all tangential to discussions we want to have about a document that don't necessarily elicit changing it.

T3353 isn't specifically all about "review" if you read through the task. That task is the currently point for all things "we want to discuss changes on a document". I think that could include:

  • Inline Commenting
  • Real Time Collaboration (Conpherence?)
  • Pre/post change commenting
  • Full Review structure.

Personally, I think just adding commenting to Phriction doesn't get us anything new and opens up a can of worms like Evan mentions. I'd rather find a way to solve multiple problems with something that is uniquely tailored to Phriction. Otherwise Maniphest, Legalpad, Phame all sort of have the same features with little differentiation or reason for existing.

Well we could use Maniphest for commenting on documents, except that Maniphest tasks don't have a hierarchy to them.. neither do all of those other applications.

I guess for now we could create a Maniphest task for each document we want to discuss, and put (NOTE) **Discussion:** {T1234} at the top of every wiki page, even if it does generate a bunch more work just to get comments.

The scope of what's described in T3353 is massive, and my guess is it will approximately take infinity years to get built and be usable enough for daily use since it's basically "Differential for human-readable text".