Preamble

Idea: 173-documentation
Title: Status Documentation
Status: Draft
Created: 2018-05-31
Requires (*optional): <Idea number(s)>

Summary

A new-and-improved home for Status documentation, with fresh information and a plan for continuous maintenance.

Swarm Participants

  • Lead Contributor:
  • Contributor:
  • Contributor:
  • QA:
  • PM (required for user-facing):
  • UX(R) (required for user-facing swarms):

Product Overview

The Status wiki is collecting cobwebs. Much of the information is out-of-date and further, the wiki hasn’t gained traction as a resource.

The goal of the wiki is to share knowledge and make it easy for developers to get involved with Status. This swarm aims to better fulfill that need by:

  1. Updating existing content and proposing additional, if appropriate
  2. Building a static site to host our documentation (reference Embark)
  3. Forming a strategy to keep documentation up-to-date in the future

Update existing content and propose additional

  • A team of contributors will review the existing wiki and mark content as irrelevant, relevant/outdated, or relevant/current.
  • Swarm will gather a list of additional documentation that should be written or included by working with teams across the organization.
  • Additional documentation is not required for the completion of this swarm; the main emphasis is on migrating the wiki materials and creating a process for future docs.

Build static site to host documentation

  • During a discussion on Slack, it was agreed that a static site which contributors can write to in markdown is a happy solution for now.
  • Swarm will decide on a potential architecture of information for the documentation site.
  • Site to be hosted on Github Pages, same as Embark and ethprize.io.
  • Swarm will decide on a static site generator to use, or to build from scratch.

Strategy to keep documentation up-to-date

  • Swarm will propose a workflow that teams can follow to keep documentation up-to-date.
  • Swarm will get feedback and buy-in on the strategy.

User Stories

  • A developer follows the quick start to build Status on their device and begin working on a status-react issue.
  • A developer learns about Status’ handling of push notifications, mail servers and messaging by reading the docs.
  • A developer follows the extensions documentation to build a native integration for their DApp. [future scenario]

Requirements & Dependencies

Participation from Core teams to create and edit documentation.

Security and Privacy Implications

Dates

TBD once swarm participants are identified.

Minimum Viable Product

Goal Date: 2018-06-08

Description:

  • Wiki content is reviewed
  • New content proposed—should we include Readmes? New content is not a requirement
  • v1 content architecture agreed upon
  • Website generator, if using, agreed upon—Gatsby, Jekyll?

Iteration 1

Goal Date:

Description:

  • Existing wiki content is updated
  • Any new content in progress
  • Design assets for site prepared

Iteration 2

Goal Date:

Description:

  • Website created, content migrated
  • Plan for maintaining documentation proposed

Note: translatiosn can also be considered at this stage.

Success Metrics

  • A developer can complete a set of required tasks by following the Status documentation.
  • Community feedback is positive.

Exit criteria

  • New Status documentation website is live
  • Organization-wide buy-in for maintaining documentation

Supporting Role Communication

Sync with marketing, Embark and community teams

Copyright and related rights waived via CC0.