Set up User Contributed Notes for code reference

[viktorix]

Set up "User Contributed Notes" for code reference using comments.

• Moderated and approved before being published.
• Need to ensure code highlighting works.

[joyously]

Yesterday's WP docs meeting had a thread about moderating the comments.

Jb Audras
9:31 AM
Quick open floor question: is there anyone else than the people listed here that is also currently curating Devhub User contributed notes?That’s not a problem (at all!), but I have a few recommendation on how I’m handling them since one year or two 🙂
I see plenty of comments approved that would not have been approved that quickly as per the previous (but not documented, sigh) workflow. Some of them are not very relevant (like classic “thank you messages”). Most importantly, some of them need to be addressed on Trac (docblock errors). In this case, I never publish the comment but I rather open a Trac ticket and mention the commenter for proper Core Props attribution.

He said he would draft up some bullet points on moderating the comments.

[viktorix]

Thanks for sharing. Let's keep an eye on that. If you see the draft of bullet points, then do post it here. I think the common sense in this situation should suffice:

• if it doesn't explain anything or add additional information/code, then it shouldn't be posted
• issues/errors should be opened in the appropriate place, core repo or docs issue tracker for issues with the notes
• no external (non-CP) links unless it's in the code snippet using public CDN for assets (JS/CSS) or a link to a ClassicPress's GitHub issue/PR
• Code snippets should be functional and not cause an error/warning/notices
• Reviewer can request second review if not sure

I think we should also create a "ClassicPress Bot" account which we can use to copy explanations/code snippets from WP's code reference and include proper attribution to the original user.

[joyously]

I think we should also create a "ClassicPress Bot" account

The ones that were copied from the codex have "Codex" as the account. The attribution is a bit muddy there, but copying code from WP Code Ref is covered by the GPL part of the licensing, so it could say "Codex" also.

The WP docs team has a guy that is starting to go through all the code examples with the coding standard. I think that's a bit much and would rather see them tested to be sure they do what is intended. (But most are pretty simple.)

[viktorix]

It looks like UCN are already built-in, just not implemented in the frontend:

This makes implementation easier.

[viktorix]

Adding one more note about the process user would have to go through to leave a note:

1. This would not be public. The user would have to be registered with a subscriber role.
2. We have integration between Discourse and docs site where members of specific groups in the forum are created (and used for SSO) in the docs site. Right now, those groups are admins and authors. Groups are private. I'm thinking of creating a group for subscribers and making it public, so any forum user could join the group and become a registered subscriber on the docs site.
3. Once they log in to docs site using Discourse SSO, they will have a comment form to leave a note.
4. Notes will be moderated and reviewed before publishing.

This process will ensure there's no spam. We will provide instructions/guidelines for the users.