Polykey-Docs 1.0: Revamping the PK-CLI set-up Guide under Getting Started Category

CryptoTotalWar commented 3 months ago

We've rearranged the sidebars structure so that navigating to relevant documentation is facilitated though the sidebar menu rather than having to click within multiple containers.
We've invigorated our approach in structuring the docs using the Divio system and referencing other best-practices and industry examples that utilize these principles but vary in their implementation.

The Implementation approach I have chosen to pursue is as follows:

We're running into the additional scope of work issue where this change in direction, requires 2 things:

revitalizing our tutorial documentation to be more tutorial oriented rather than reference oriented.
restructuring our pages and migrating the previous version documentation into polykey commands reference.
What do we want to include in our getting started guide?
- [x] Setting up Polykey: Which involves installation and bootstrapping first node
- [x] Linking your node to an identity via GH
- This issue is tracking the set-up which i believe involved these 2 pages above as a 100% requirement. However, in order to publish this, we have an entire CLI container category with previous tutorial documtation that we need to stash for later use in migrating much of this info in the Polykey-CLI commands reference documentation.
(link ticket tracking that doc migration issue here)
- The scope of this ticket doesn't even mention contributor guides, the home page (which being the first page absolutely needs some tending to), or the Polykey client library getting started docs.
- contributor guide: we have an issue tracking this (link here)
- Home page revamp: we have an issue tracking this (link here)
- Polykey client library getting started docs: we have an issue tracking this (link here)
- Conversation/Feedback on the team on what else should be in the getting started docs:
- I previously mentioned this could include 2 more pages
  - page 3: copying txt files that represent key pairs (secrets), creating vaults, and showing how to view the secret using pk or inject into a session
  - page 4: Showing how to share secrets that can vary based on 2 scenarios: Pair programming session or via managing a 2nd node.
  For the purpose of completing/publishing development in this cycle: I will create a new branch for the pk-cli reference documentation that will contain the outdated tutorial documentation because much of that can still be referenced. I will then delete that outdated documentation from this branch.
  
  All that will be left is the home page, pk-set-up page, and connect identity page. I will also leave the polykey Core container because we will be adding an installation guide and brian will be creating a tutorial guide for this as well, but this is down the line (short term).

Specification

[x] PK "Set-up" is just 1 index page that contains the PK-CLI installation instructions and the bootstrap process that users engage in upon launching Polykey for the first time.
[ ] Final Review of PK "Set-Up"

Documentation Review Checklist for the Set-Up Polykey Page
Ensure the following aspects are reviewed and updated as necessary before moving the documentation to production:
[ ] - Team member input: Get team member's to weigh in on this page.
[ ] - Consistency in Command Display: Verify that all command blocks (pkcli) are consistent throughout the document.
[ ] - Stopping the Polykey Agent:
[ ] - Expand the section to explain why a user might need to stop the agent.
[ ] - Describe what happens when the agent is stopped.
[ ] - Visual Aids:
[ ] - Add screenshots or diagrams after major steps to enhance understanding, especially for visual learners.
[ ] - Manual Installation Method:
[ ] - Clarify instructions within the Manual Installation tab.
[ ] - Ensure all links within this section are correct and up-to-date.
[ ] - Link Verification:
[ ] - Double-check all hyperlinks to ensure they are operational and lead to the intended pages.
[ ] - System Requirements:
[ ] - Specify which versions of Node.js and npm are supported to prevent installation issues.
[ ] - Security Warnings:
[ ] - Include any relevant security considerations or warnings related to manual installations or configurations.
[ ] - Missing Content in Manual Installation:
[ ] - Review and add any missing details that might be crucial for users opting for manual installation.

[ ] Claim your identity

Documentation Review Checklist for Claiming your Identity

[ ] Create new branch to save the outdated pk-cli container of documentation that will be synthesized into reference info.

[ ] Ensure tickets are linked to the following:
- contributor guide: we have an issue tracking this (link here)
- Home page revamp: we have an issue tracking this (link here)
- Polykey client library getting started docs: we have an issue tracking this (link here)
- Conversation/Feedback on the team on what else should be in the getting started docs:
- I previously mentioned this could include 2 more pages
  - page 3: copying txt files that represent key pairs (secrets), creating vaults, and showing how to view the secret using pk or inject into a session
  - page 4: Showing how to share secrets that can vary based on 2 scenarios: Pair programming session or via managing a 2nd node.

Related tickets

PRs created

101

linear[bot] commented 3 months ago

PRO-200 Polykey-Docs 1.0: Revamping the Installation Guide / Getting Started

CryptoTotalWar commented 2 months ago

Some Updates here.

The revamped Polykey Set Up Tutorial Instructions Is almost ready in #92

This will be the first Item of completion this Cycle 10. In addition, we now also need to have a ticket tracking further development of the Home Page, Installation on PK-CLI on Docker, Contributor Guide documentation, and moving PK-CLI reference information in a relevant category structure.

MatrixAI / Polykey-Docs