Idea: 308 Title: Ducmentation Status: Draft Created: 2018-09-25
We need to manage documentation better, in accordance with the findings in ethreport.info. Documentation has been a long-running battle at Status because our codebase moves so fast, but with a good team managing it, with clear responsibilities and an easy contribution pipeline for anyone to edit and update our docs, we can become the best-documented project on Ethereum.
I have called everyone I need
janitors rather than
leaders or any other term in line with Swarmwise, the summary of which you can find here. We need people to serve their teams, clean up after all the amazing work that is being done and ensure that it is properly documented at all times.
- Lead Contributor: @andytudhope
- Contributor: @easye
- Contributor: @rachelhamlin
- Evaluator (defaults to lead contributor):
- Contributor: @jakubgs
- PM: @rachelhamlin
- Janitor: @jeluard
- Janitor: PombeirP
We have changed our documentation to use the same theme as the Embark docs: hexo.io. All technical documentation will use this theme going forward, and we will style it according to the designs created by Hazel and Andrei. We will also implement a global header navigation, so that it is easy to move between all the different parts of Status, no matter where you are in our online web of information.
We will also set up the current repo so that the
master branch serves to
docs.status.im and the
develop branch serves to a staging site. That way, anyone can commit directly to
develop, see the changes themselves, and submit a link for review so that the process can run as smoothly and quickly as possible.
Documenting all the disparate parts of Status has always been a challenge. Rather than coming up with specific user journeys when we still have so few actual users seems to be the wrong way to go about building a great documentation site. I think we should rather make it as easy as possible for people to contribute to a really good-looking documentation site, and then craft user journeys out of the content we see generated across the organisation.
With a good global navigation, the same theme as our other sites, and an easy-to-use and review pipleline, we can make sure that each project can easily maintain their own documentation adn that Status remains - as a whole - the best documented project in addition to the most active developer one. We need to achieve this is in the service of mass adoption of Ethereum because good education precedes mass use and acceptance.
It also contributes greatly to many of our principles, especially
- Style hexo.io to Hazel and Andrei’s new designs.
- Work with Jakub to set up the pipeline detailed above with
developserving to different places so that we don’t end up with the mess of branches currently accumulating there.
- Set up the
Edit on GitHubbutton on each page to edit directly on
developand build the changes submitted so that it’s automatic to see the effect of your changes as a contributor.
- Think about how we can use Swarm and/or IPFS to serve our docs.
- Think about incorporating user feedback mechanism like the
SNT clap@exiledsurfer is planning for the blog.
- I want to understand how to build Status easily so I can contribute to the core codebase.
- I want to understand how to build Desktop easily so I can contribute to the core codebase.
- I want to understand how I can use Status to connect to my DApp.
- I want to understand how I can leverage the unique features of Status in my DApp.
- I want to add my DApp to the Status store and optimise it for Status.
- I want to understand the research happening on Nimbus and how to contribute (will be split into it’s own site when there is enough content, using the same theme).
- I want to understand the technical details of Status’ protocols: how does Whisper work? how does X3DH key exchange and PFS work? What is different about
status-go? How does LES and ULC work?
- How can I use SNT? From voting to Tribute to Talk to how to run a mailserver (this all needs to be detailed still).
Requirements & Dependencies
Final design from Hazel and set up with Jakub.
Security and Privacy Implications
None at the moment. Will follow up with @corpetty though.
Final Design and Pipeline Setup 2018-09-28
Detailed explanation for CCs on blog 2018-09-29
Re-style omplete 2018-10-10
Minimum Viable Product
Site that uses hexo.io to generate pages, is styled according to our designs, and has a slick build pipeline that anyone technical can easily contribute to. Some semblance of a structure, with enough room to evolve into what it really needs to be.
- 4-8 new contributions a month
- 2-4 updates a month to existing docs
- 5 tutorials fully written by November
- Technical spec for whisper complete and accessible
- Technical spec for PFS complete and accessible
- 3 clear Nimbus docs on what it is, what the state is now, and how to contribute
- Lots more comments like the one in slack on 2018-09-26 about the doc Julien shared being “exactly what I needed!”
Supporting Role Communication
We’ll need help from Michael and Jonny to get the really good docs out and communicated across the community, especially tutorials.
Copyright and related rights waived via CC0.