Skip to content
This repository has been archived by the owner on Nov 5, 2021. It is now read-only.

Latest commit

 

History

History
133 lines (98 loc) · 6.83 KB

308-documentation.md

File metadata and controls

133 lines (98 loc) · 6.83 KB
Raw
id title status created category lead-contributor contributors exit-criteria success-metrics clear-roles future-iteration roles-needed okrs
308-documentation
Documentation
draft
2018-09-26
multi-category
andytudhope (Andy Tudhope)
easye
rachelhamlin
jeluard
hazel
Jakub
false
re-styled according to Hazel's designs to match web-refresh
global header navigation to move across all Status domains
clear documentation that is easy to contribute to and manage
kept up-to-date month on month, with at least 5 contributions and 2 tutorials
clear user journeys established once content is flowing
false
true
Nimbus janitor
Hardwallet janitor
Technical tutorial writer (perhaps video too?)
Communication janitor
UXR janitor
Developer Relations (get 240 monthly visit to documentation)

Preamble

Idea: 308 Title: Ducmentation Status: Draft Created: 2018-09-25

Summary

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.

Swarm Participants

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.

Product Overview

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.

Problem

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 openness, inclusivity,transparency, decentralization and continuance.

Technical solution

  • Style hexo.io to Hazel and Andrei's new designs.
  • Work with Jakub to set up the pipeline detailed above with master and develop serving to different places so that we don't end up with the mess of branches currently accumulating there.
  • Set up the Edit on GitHub button on each page to edit directly on develop and 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.

User Stories

  • 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.

Dates

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.

Success Metrics

  • 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

Copyright and related rights waived via CC0.