A better way to discuss PEPs

Hi everyone,

CQ2 is an open-source document discussion tool we’re building.

We took the Discourse discussion on PEP 736 and simulated it on CQ2. Check it out here and try opening a few threads!

Discourse lacks threads and inline comments. Replies to topics are spread all over the place and discussions turn into a mess. We think the discussion on CQ2 looks much better organised, easier to follow and easier to engage with, because it’s designed for thoughtfully engaging with the content (the PEP).

CQ2 offers a better way to discuss documents like PEPs — inline comments (no more quote hell, and also know what’s been discussed and what hasn’t been), threads inside threads are allowed (every topic has a place, no more talking over each other and there’s a separate place for general comments), threads can be concluded (so know what exactly remains to be discussed) and there’s a tree feature which lets you quickly go to any thread you want. And we’ve more quality-of-life features in the works.

It also has better document version tracking to easily know what the original content was before a change made after a discussion. Each document version has not just the content but the discussion associated with it too. Not sure if that feature would be used by you all since there’s a workflow on GitHub to create and update PEPs.

We’re excited to hear your thoughts and questions!

P.S. I’m an ex-GSoC student with the PSF (LiberTEM) and my co-founder (Sreelakshmi) is a GSoC mentor (and an ex-GSoC Student) with the PSF (Mission Support System).

Thanks,
Anand

3 Likes

I am not really ok with the way you used the data from the discussions thread here :frowning:

It looks like I already used your project, which makes it seem like an endorsement. It’s also a violation of the license CC BY-NC-SA 3.0, which requires attribute (I guess the name is good enough for that), but “not in any way that suggests the licensor endorses you or your use”, which you are violating IMO. Also, your site is missing a clear link back to the discourse discussions and a clear display of the license (since everything on your site, or at least this document also has to fall under CC-BY-NC-SA 3.0).

1 Like

This is a blocker:

CQ2 is not optimized for mobile use, yet.

Please try on a desktop or laptop.

7 Likes

I can’t see why this would be better than a pull request on GitHub (or other code forge), assuming a technical audience that speaks Markdown/reStructuredText. GitHub doesn’t have sub-threads, but it allows commenting on a line/group of lines, allows code suggestions inside comments (which can be accepted and committed by the PR author) and already handles revision control.

It’s easy to miss a discussion about a paragraph, since they are only signified by highlighting. A better approach might be to always show them. Also, if you’re doing a pop-over with a lot of content, I would have expected to be able to hover the pop-over to scroll it, but it disappears.

2 Likes

Also, “not optimized” implies that it works but not well, whereas in fact it doesn’t work at all (even if you “request desktop website”).

1 Like

Hi Cornelius! I agree. I’ve put the details properly now:

image

There was a link to the discussion before, but yes, it wasn’t clear (only showed up on title hover).

3 Likes

Can you please check it out on desktop/laptop when you get some time later? We’ve not gotten around to exploring and building the mobile interface yet. I missed to say this before: CQ2 is in the alpha stage right now – we started actively building it in May and started exploring the problem in January.

Makes sense! I’ve changed “optimized” to “ready”.

1 Like

I can’t see why this would be better than a pull request on GitHub (or other code forge), assuming a technical audience that speaks Markdown/reStructuredText. GitHub doesn’t have sub-threads, but it allows commenting on a line/group of lines, allows code suggestions inside comments (which can be accepted and committed by the PR author) and already handles revision control.

Interesting. It’s my first time hearing and thinking about using GitHub PRs for document discussions. Regarding why CQ2 would be better: the foremost feature of its design is the N-level threads combined with the ability to quote anything (not just line/lines). That provides organisation to the discussion and prevents quote hell. You can see in the demo (using the tree) that the threads went up to 4-levels deep and there’s no quote hell. And, this is what we call the “quote hell”:

So for document discussions, I think it’s CQ2 > PRs > Discourse.

It’s easy to miss a discussion about a paragraph, since they are only signified by highlighting. A better approach might be to always show them.

Interesting! You mean the highlights are not easily noticeable due to them being blended in with rest of the content, right? I’ll explore doing something like Google Docs’ comments, but less intrusive.

Also, if you’re doing a pop-over with a lot of content, I would have expected to be able to hover the pop-over to scroll it, but it disappears.

Ah, that’s not complete, we’re working on the disappearing part.

The product is not yet ready in order for us to consider it as an alternative for PEP discussion forum. Mobile support is a requirement IMO.

12 Likes

CQ2 looks interesting and potentially useful. I have to say though that I’m developing a bit of a pet peeve about nascent projects being recommended as alternatives to established tools before they’re even complete. You yourself said in a later post that CQ2 is in alpha stage. Can you seriously recommend this tool for general use, or say that it is a better way to discuss PEPs than existing ways?

I don’t want this to come off as too harsh, but I feel like I’d have a much more positive view of the tool if it were presented more like: “We’ve been working on a tool that we think might be useful for discussing things like PEPs. It’s still in an alpha stage and doesn’t support X and Y but has nice features P and Q. We’d be interested in hearing what people think of this approach or if there are key features that would be needed to make this better than the existing Discourse discussion process.” That is, present it as what it is: an incomplete attempt at producing something that may eventually become better than the current system — not a complete, robust alternative.

3 Likes

I think there was a misunderstanding because I missed to mention about the alpha/early stage, and I apologize for that. To clarify: CQ2 is not ready to use right now. There are many things remaining to build which we’re working on - mobile support, full fledged editor, inbox, emails, important quality-of-life features, etc.

As I mentioned before, the core feature of its design is the N-level threads combined with the ability to quote anything. That is complete and that is the reason why the discussion on CQ2 already looks much better organised, easier to follow and easier to engage with. Hence, it is a better way to discuss PEPs, but it’s not complete. Also, it is a tool specifically built for document discussions - existing tools (Discourse, Google Docs, GitHub PRs, etc.) aren’t.

I should have made it more clear. What I meant was: I’m excited to hear what you all think about the demo on CQ2 vs the original discussion, what features could be improved and how, what’s missing, any questions, etc., and have you help shape the product in its early stages. We already got 2 interesting ideas/insights from this community!

1 Like

If you’re interested in targeting the community here that discusses PEPs, then support for full participation by users who prefer to interact through an email client will be important. We have a number of community members (disclaimer: I’m not one of them) who aren’t willing to use a web interface for participation, and a limited or non-functional bidirectional email gateway will therefore risk excluding people from participation.

4 Likes

Robust moderation tools are also absolutely necessary.

And you’ll need to convince everyone to sign up for yet another service, which is going to be an uphill battle on its own since we already made the decision to consolidate discussion here.

It seems like you’ve gone about this the wrong way. Rather than asking the PSF, board, or steering council whether a new system was needed, then collecting requirements and building something, you did the opposite. You built a thing first, then copied other people’s discussions there without asking, then asked us to help you develop your unasked for tool by giving you free QA and feedback. And you’re using that example to advertise on your home page, implying that the PSF has approved of this. That’s not a good start.

10 Likes

whether a new system was needed, then collecting requirements and building something

We didn’t start CQ2 specifically for this community. We started it because we faced the problem, then iterated several times on the design, went #2 on HN and got 231 people on our early access list. We approached this community because PEP discussions are the most ideal use case we’ve seen so far. Looking forward to hearing everyone’s thoughts on how the discussion looks on CQ2 v/s the original!

And you’re using that example to advertise on your home page, implying that the PSF has approved of this.

Sorry, we didn’t know it would be interpreted in that way. We’ll stop using the PEP discussion for the demo.

3 Likes

This is nigh vitriolic. You’ve made a host of assumptions on the author’s motives and assumed a posture which is less than kind. There’s no need to put “unasked for” in writing - keep it to yourself.

12 Likes

What are your thoughts on accessibility for CQ2, for, say screen readers? As an example, I opened the demonstration link in Firefox and chose Reader mode to see what the “plain text” version, and I only saw the original PEP text: the comments did not appear.

I am no expert on this, but I’m aware of the necessity. I think it would be good to engage with some users and experts who would need and would know about accessibility features to help to read and navigate a CQ2 page, including screen readers, keyboard-only access, etc.

2 Likes

Setting aside the framing of the thread, which I agree could have been much better—I like the tool. It is a promising prototype. I agree that linear forum threads are hard to follow and I think the core problem you’re addressing is indeed real.

(I do find it a bit funny that, after years of discussions moving from mailing lists to forums, this looks closer to the threaded view of a mailing list conversation :slight_smile: )


That said, I think calling this “A better way to discuss PEPs” is an uphill, and ultimately losing, battle. A large and diverse community like this one requires mature tools (e.g., mobile support, screen readers and other accessibility features, mailing list interfaces, moderation, data retention policies, … the list goes on).

I would encourage you to develop this with another group—one that is smaller and has lower switching costs for trying something new. Again, I like what you’ve built, but it seems like you misunderstood the audience on this forum.

8 Likes

Personally I also find this to be more of a “product pitch/advertisement” so I think this discussion is off-topic for this category.

2 Likes