voteflux / flux-docs Goto Github PK

@dfraserau - ticket for our functional spec

@pwhipp - re: constitutions and docs, would it be possible to add voteflux/flux as a submodule of voteflux/flux-docs? I haven't worked with submodules much so not sure how they'd play with sphinx or readthedocs, but that might allow us to keep the constitutions always being build from the POT source - otherwise we'll need to put a notice or something on each of the constitutions in this repo since they're not "official"

(the other problem is that synchronisation is manual atm which is obvs not great)

(another note: not sure if markdown plays well with restructured if they're used at the same time in sphinx; constitutions are all in markdown)

I've been watching Netlify's CMS for static sites for a while (https://www.netlifycms.org/)

The idea is it integrates with various static site generators (jekyll / hugo / etc) and allows non-git ppl to edit the source for a static site in a user friendly way.

Netlify CMS is adaptable to a wide variety of projects. The only inflexible requirement is that your site content must be written in markdown, JSON, YAML, or TOML files, stored in a repo on GitHub.

So it sounds like it should work with sphinx...

This issue is to track discussion and possibility of using this to massively simplify workflow for non-techy-ppl

@pwhipp - CCing you on this bc I think it was mentioned you were willing to train people or that sort of thing. I noticed you had instructions on python stuff in the readme, so this sort of thing could help a bunch to keep it KISS for new ppl

In https://docs.flux.party/en/latest/docs/contributing/index.html the term "PR" is used as an acronyms of "pull request" but is not defined so could confuse the lay reader, we could add this in brackets after the first reference to pull requests, or we could make a rule to not use acronyms/abbreviations?

This section can be a push down list of release documents with eventual date organisation.
If anyone has some recent media release documents I can add them to create a good starting point.

Generally a media release will be a timed push to the repository from some appropriate private repo or file.

Can anyone provide some links to media release documents here?

On https://docs.flux.party/en/latest/docs/contributing/index.html it states a good path before making changes is to create an issue, but it does not explain what this means, how to do it. I would suggest a separate page with instructions how to.

(I think we should present information with the assumption the reader has no knowledge of Git or any other processes we are using)

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.

README link in this repo https://docs.flux.party/en/latest/ is broken.

1. SSL cert error from CloudFlare ssl403572.cloudflaressl.com, maybe a configuration option has become outdated.
2. 403 response to route.

The pdf is here .

If someone can give me a link to the word doc, I'll add it to the repo.

At the moment it seems "Flux SteerCo" and "National SteerCo" are used interchangeably see:

https://docs.flux.party/en/latest/docs/contributing/index.html

I would suggest in the docs we use one term than encompasses international movements under the umbrella SteerCo, my preference is "Flux SteerCo" as it is already in use, but we could come up with another term.

If this is agreeable can I begin making changes to the docs to reflect this?

Any document in this repo may be referenced using a specific commit as was done for the ACT constitution (but not the other constitutions btw).

In the source constitutions file we had:
CONSTITUTION.ACT.md is accepted and ratified as the opening constitution of Flux ACT as defined in commit c37c68126e3c9d354d8bb66496d8efd6d9b35caa which is verified (and provided) at the following URL: https://github.com/voteflux/flux/blob/c37c68126e3c9d354d8bb66496d8efd6d9b35caa/CONSTITUTION.ACT.md (note the commit hash - the long string of randomish letters and numbers - matches the commit hash in the URL, indicating the document is correct and not tampered with).

As the constitutions file itself was not hashed, this text has been removed for the time being making ACT the same as the other constitutions.

I'm unsure of the legal requirements here but the entire constitution folder could be hashed and we could have another special (signed) document containing the hashes.

Signing a document means taking its hash and encrypting it with a key such that the document cannot be changed without invalidating the signature. The signature can easily be checked but cannot be 'forged'. We would be better signing the constitutions and storing the signature. If necessary code could be added to present a 'signature valid' badge.

Once we've finalised a signing process, the constitutions will need to be updated to reflect this.

Please add a 'shop' or 'merch' tab to the main website. It should link to the following with an instruction to 'open in new tab':

https://www.grovewesley.com/store/c33/Flux_Merchandise.html

Thank you in advance, Ali