This is an attempt to organize soledad's documentation according to ideas explained in this article.
- Current documentation
- Proposed structure / wishlist
- Current structure of https://soledad.readthedocs.io/
- Current structure of https://leap.se/en/docs/design/soledad
- What is missing in current documentation
- Proposal
Current documentation
Current pieces of documentation for soledad are:
- https://leap.se/en/docs/design/soledad (a lot of discussion, some reference, a bit of how-to).
- https://soledad.readthedocs.io/en/latest/ (a lot of reference, some discussion, a bit of how-to).
Proposed structure / wishlist
- Tutorials (learning oriented) (T)
- How-to guides (goal oriented) (H)
- Discussions (understanding oriented) (D)
- Reference (information oriented) (R)
Current structure of https://soledad.readthedocs.io/
- Soledad Client
- Soledad Server (R)
- General information (R)
- Server database organization (R)
- Server Configuration File (R)
- Authentication (R)
- Authorization header (R)
- Services API tokens file (R)
- Implementation (R)
- Reference
- Environment Variables (R)
- Document attachments (D)(R)(T)
- Soledad “Incoming Box” Specification (R)
- Development
- Contributing (R)
- Backwards-compatibility and deprecation policy (R)
- Tests (R)(H)
- Benchmarks (R)
- Changelog (R)
- Migrations
- Soledad Server 0.8 to 0.9 - Couch Database schema migration needed (R)
Current structure of https://leap.se/en/docs/design/soledad
- Introduction (R)
- The importance of data availability (D)
- Goals (D)
- Related software (D)
- Soledad protocol
- Document API (R)(T)
- Storage secret (R)(T)
- Document encryption (R)(T)
- Document synchronization (R)
- Document IDs (R)
- Re-keying (R)
- Authentication (R)
- Bootstrap and recovery (R)(T)
- Reference implementation of client
- Local storage (R)
- Encrypted synchronization target (R)
- Reference implementation of server (R)
- CouchDB backend (R)
- WSGI Server (R)
- Tests
What is missing in current documentation
- server http api (sync, blobs, incoming)
- tutorials, how-tos
Proposal
- Have only minimal and conceptual information in https://leap.se/en/docs/design/soledad
- Review and update all documentation, move to https://soledad.readthedocs.io/ (managed through the soledad repository)
- Work on the structure of the documentation according to references.