swarms/173-documentation.md

id	title	status	created	category	lead-contributor	contributors	exit-criteria	success-metrics	clear-roles	future-iteration	roles-needed	okrs
173-documentation	Status Documentation	draft	2018-05-31	core			yes	yes	no	yes	QA UXR Clojure dev Designer Community

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

Copyright and related rights waived via CC0.