mirror of https://github.com/status-im/swarms.git
139 lines
4.1 KiB
Markdown
139 lines
4.1 KiB
Markdown
---
|
||
id: 173-documentation
|
||
title: Status Documentation
|
||
status: draft
|
||
created: 2018-05-31
|
||
category: core
|
||
lead-contributor:
|
||
contributors:
|
||
-
|
||
-
|
||
-
|
||
exit-criteria: yes
|
||
success-metrics: yes
|
||
clear-roles: no
|
||
future-iteration: yes
|
||
roles-needed:
|
||
- QA
|
||
- UXR
|
||
- Clojure dev
|
||
- Designer
|
||
- Community
|
||
okrs:
|
||
-
|
||
-
|
||
---
|
||
|
||
## 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](https://embark.status.im/docs/))
|
||
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](https://status-im.slack.com/archives/CAB6WB38X/p1525340980000332), 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](https://www.gatsbyjs.org/), [Jekyll](https://jekyllrb.com/)?
|
||
|
||
### 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](https://creativecommons.org/publicdomain/zero/1.0/).
|