Flux Documentation

[XertroV]

We need some flux documentation that covers basic policy, party setup, philosophy, IBDD, etc

current plan is to use sphinx - See example: http://fluxdoc.readthedocs.io/en/latest/ (sphinx site: http://www.sphinx-doc.org/en/master/)

Ideally we'll host this on our own domain, maybe a good use for https://docs.flux.party

Also we need to have on the roadmap some sort of discussion integration - e.g. a link on each page to "discuss this" or something. Using a service like disquss isn't great bc we don't own the data and it's very poor for any sort of technical discussion (e.g. bad quoting support). Could tie into a github-issues based forum as mentioned in #1

[XertroV]

Alternative to sphinx (static site + documentation):

• Hugo (sample documentation themes below) - https://gohugo.io/
  -- https://themes.gohugo.io/hugo-theme-learn/
  -- https://themes.gohugo.io/docuapi/
  -- https://themes.gohugo.io/docdock/
  -- some info on content management with hugo (seems to use markdown) https://gohugo.io/content-management/organization/
• jekyll + markdown

[sventhebarbarian]

I agree https://docs.flux.party is a good location for this, I think we can achieve both technical and documentation for presentation to newly initiated people in the one structure, saving admin overheads.

Hugo looks interesting but my support would be for Sphinx/Github at the moment, mainly because we already have it, and there has been some interest from supporters that it is a good solution, whereas I have not seen anyone mention Hugo in the previous discussions so assume there is less experience out there.

Github has strong benefits such as forking/merging/ease of making backup copies of the entire VCS, all within well understood standards. Not sure if Hugo offers these.

Regarding discussion I believe others have discussed using Githubs existing systems, is there a way for people who are not contributors to the Github repo to create issues or comments, preferably per document? If not is there a way to make a "team" under the repo that only has access to comment/make issues, we could have a quick method of signing anyone who requests up to that team and use eg issues as a way to discuss things? Maybe not as clean and simple as a forum but nice to keep everything in a single service.

[XertroV]

Hugo is a static site generator so would compile directly from github (much like vote-flux-v2 does now)

Sphinx is okay but is not nearly as powerful / customisable as jekyll/hugo/whatever - good for docs. That said Hugo and Jekyll both have docs themes.

[sventhebarbarian]

@pwhipp Paul has done most of the setup of the Sphinx site, have you looked at the alternatives Max has mentioned? It would be nice to be able to work in more media rich content if desired but I guess ease of management and on-ramping supporters is a consideration as well.

We should probably make the decision now at this early stage so not need to migrate later after a lot more content has been added..

[XertroV]

As context: in terms of docs I'm v happy with sphinx (just haven't used it much before). Hugo/Jekyll/etc are more geared towards main site or other stuff.

[sventhebarbarian]

Max thinking about your comments of having a place to discuss things, this is something I have been mulling for my own project, my project is a large community driven marketplace and I wanted to achieve a few things regarding documentation:

• Really simple static pages for new casual members to get a quick oversight of the ideas/policies. In Flux this would be similar to the pages displayed on http://voteflux.org

• A more complex public facing description of each element of the sight, including each of the static pages above, explaining that elements purpose and design in detail. This would be maintained by the community. In my case I was considering a wiki for this (although some of the ideas we are talking about could also be used), the discussion area of the wiki would be a place to discuss actual changes and formatting of the wiki page - but not its content so much.

• Lastly I wanted a forum where all ideas can be floated and discussed prior to being placed in the wiki (and ultimately the static presentation pages - or any other design element of the site), this would be per element as well. I was considering a forum structured within folders etc but have not narrowed down which service yet.

All of these would be linked together so you could switch between the three on a per element basis. It is messy though and could be confusing to casual visitors, trying to make it cleanly link might be a bit of work.

[pwhipp]

@sventhebarbarian : I don't have any experience of hugo but I've worked a lot with cms and some substantial document management solutions. My liking for sphinx is based mostly on experience and flexibility - we can add to its capabilities to suit our needs over time.

The sphinx solution is not rich media or powerful for presenting websites but that could be seen as an advantage given that I see it as the POT for flux documentation - not a replacement for the promotional websites... or necessarily for working group working documents although any public document should end up in flux-docs for consistency and easy of reference in the long term.

We should resist additional wikis etc. if possible though, so that we retain a single clear POT for all flux documents.

Linking a working doc to issues/slack pages seems like a good way to start with tying the documents to discussions.