search

MatrixAI / Polykey-Docs

Documentation for Polykey
https://polykey.com/docs/
GNU General Public License v3.0
1 stars 5 forks source link

Launch Revamp #32

Closed CMCDragonkai closed 1 month ago

CMCDragonkai commented 7 months ago

In preparation of a CLI beta launch, we need revamp the documentation to explain to new users how to use Polykey.

Many parts of the documentation is out of date, so plenty of should be thrown out.

There's also lots of the pending issues here in this repo.

There are 4 main kinds of documentation:

  1. Tutorials
  2. How-To Guides
  3. Explanation
  4. Reference

This is a new skeleton for the pages that we want.

  1. Tutorials - we want to provide a narrative that new users can follow, each new page represents another chapter that the user can follow through on
    • Polykey CLI
      • Installation
      • Getting Started
      • Bootstrap your Root Keypair
      • Manage Vaults
      • Manage Secrets
      • Connect to the Global Network
      • Claim your Digital Identity
      • Share Vaults
    • Polykey Desktop - coming soon
    • Polykey Mobile - coming soon
    • Polykey Core
      • Installation
      • MatrixAI/Polykey-Docs#9 - "Getting Started" - this is focused on the library
      • Setup Database
      • Key Management
      • Node Management
      • ...
  2. How-To Guides
  3. Theory
    • Secrets Management
    • Delegation of Authority
    • Decentralized Trust Network
    • Centralized vs Decentralized Platforms
    • Glossary
  4. Reference
    • Architecture
    • Polykey CLI
      • Commands
      • Bootstrap
      • Agent
      • Nodes
      • Secrets
      • Keys
      • Vaults
      • Identities
      • Notifications
    • Polykey Desktop
    • Polykey Mobile
    • Polykey Core - MatrixAI/Polykey-Docs#4
      • Sessions
      • Gestalts
      • Identities
      • Nodes
  5. Development Guide
    • Roadmap
    • Coding Style
    • Modular Architecture
    • Error Management
    • API Design
    • Object and Resource Lifecycles
    • Chocolatey
    • CI/CD - MatrixAI/Polykey-Docs#7
    • Input Validation - MatrixAI/MatrixAI-Graph#44
    • Timeouts - MatrixAI/MatrixAI-Graph#43
    • Release Procedure - MatrixAI/Polykey-Docs#24

In the tutorials I'm separating between the different interfaces. But I just realised that the core library doesn't really have specific workflows. Alot of things depend on other parts of the system. We should de-emphasize it too. Put to the bottom. Maybe then, it should be instead focused on how to use the subdomains.

It's important that this documentation will need to focus on Polykey CLI and Polykey library. The library is of lesser importance for now.

Tasks

CMCDragonkai commented 7 months ago

I'm going to be updating the sidebars.ts.

@addievo You should have a look from bottom-up in the contents above to see what needs updating. But you should post your changes here as comments.

addievo commented 7 months ago

Homepage links which originate from readme.md are broken.

https://github.com/MatrixAI/Polykey-Docs/assets/38064122/6018fb33-220d-4a65-af7f-d04e048363c0

CMCDragonkai commented 7 months ago

Skeleton is done. It's time to fill them in.

CMCDragonkai commented 7 months ago

Should follow this guide: https://documentation.divio.com/

@addievo start writing the reference documentation, give me the suggested information here first because I don't know if you can actually work on a branch.

You could start a separate branch off this branch and work on that first, and then I can merge in.

CMCDragonkai commented 7 months ago

Homepage links which originate from readme.md are broken.

Screen.Recording.2023-12-05.at.4.05.29.pm.mov

I removed the autoAddBaseUrl since that is what broke it. The markdown links still need to use relative paths to avoid problems in github markdown. So it's to: '/docs' now. On local dev it worked, so I've cherry picked it to master 3517d4dcfc1462400c02b4162d779d8e95d2680b.

CMCDragonkai commented 5 months ago

I've cherry picked some of the structural changes into master first, while the PR still focuses on top level work that needs to be reviewed for the launch.

tegefaulkes commented 4 months ago

Moving this to todo since it's not actively worked on.

CMCDragonkai commented 1 month ago

Cancelling as beta is done, we now focusing on the 1.0.0, and remaining docs work is now lifted to project Polykey Documentation for 1.0.0.