search

voteflux / flux-docs

Documentation for Flux Parties and the Flux Movement. Covers party setup, social media policies, IBDD and philosophy, internal practices, governance procedures, and all the stuff in between. WIP.
4 stars 7 forks source link

Discussing and commenting on documents #3

Closed pwhipp closed 6 years ago

pwhipp commented 6 years ago

The community element of this repository needs to focus on helping people collaborate over document additions and revisions.

I expect there will soon need to be a 'Proposed' or 'RFC' section for documents under consideration where the draft content does not need to be confidential. Confidential preparation (e.g. a new media release) is outside the scope of this issue.

The emphasis of this repository is static content so, if we favour e.g. slack for our community discussions, it is probably simplest to link to the community discussion at the top of documents where there is an active discussion.

XertroV commented 6 years ago

I expect there will soon need to be a 'Proposed' or 'RFC' section for documents under consideration where the draft content does not need to be confidential.

I suggest using a [WIP] tag on PRs and adding a discussion-needed label or something like that.

if we favour e.g. slack for our community discussions

Slack is okay for chat and comms but isn't a forum and is a bad place to have proper discussions:

Will still need a better place for discussion (ideally with dedicated threads), though can link both slack and whatever from the docs.

it is probably simplest to link to the community discussion at the top of documents where there is an active discussion.

Should we put the link at the top or the bottom? I feel like bottom is better (like after they've read the doc)

pwhipp commented 6 years ago

Top would get more responses but less well informed ones on average versus the bottom would get fewer responses but more informed ones. Perhaps just leave it to the authors of the doc what they want. It can be a boiler plate stating that the document is 'wip' and is in discussion.

pwhipp commented 6 years ago

I agree about slack and prefer issues like this for discussion but slack is popular. I've put an example warning on the home page that links to the slack discussion. It could have a link to one or more issues added as appropriate and would be removed on approval.

A disadvantage of this approach is that it doesn't permit comments on the document itself (other than through arbitrary temporary edits) but I prefer the use of issues (with quoting) because that is more robust and manageable, if a little harder to use.

pwhipp commented 6 years ago

I've added a warning block to the top of the home page. Blocks like this can be at the top or bottom (or both) and can link to issues and multiple discussion groups as needed. I think this does the job of linking the document to any ongoing discussion as well as allowing the status to be made clear.