Revamp Polykey Documentation Home Page

[CryptoTotalWar]

Description

This ticket aims to address and improve the current state of the Polykey documentation home page. The home page, positioned under the 'Getting Started' category, serves as the primary entry point to the documentation. The goal is to enhance its effectiveness in guiding new users and providing a comprehensive overview of Polykey's functionalities, including the CLI and client library.

Objectives and Notes

• Assessment and Planning:

  • Evaluate the current content and structure of the home page to identify what is lacking or superfluous.
    • The mention of using the divio system was superflous, it has been removed in PK-Docs 1.0: Revamping tutorials/Getting Started Documentation  #92
  • Discuss and deliberate on the essential elements that the home page should cover, such as a high-level overview of Polykey, its capabilities, use cases, and the technology stack.

  High Level Overview Orientation of the Home Page

• Quick Fixes:

  • Remove unnecessary or distracting information as an immediate measure.
  • Pinpoint critical information that needs to be included in the short term to make the home page more engaging and useful.

• Feedback and Inspiration:

  • Gather feedback from the team on the proposed changes and additional content.
  • Review other documentation sites for ideas on how to effectively structure and present the entry page.

• Iterative Development:

  • Plan for an iterative approach to continually improve the home page based on user feedback and evolving content needs.

Placeholder for Detailed Updates

• Key Sections to Consider for Update:
  • Introduction to Polykey and its ecosystem.
  • Quick start or 'Getting Started' guide.
  • Overview of documentation sections: Tutorials, How-To Guides, Theory, and References.
  • High-level use cases and benefits of using Polykey.

Conclusion

The purpose of this ticket is to initiate the revamp of the Polykey documentation home page, making it more intuitive and informative for users at their first point of contact with Polykey documentation. This revamp will be carried out in phases, starting with quick fixes to enhance current content and planning more comprehensive updates in the future. This iterative process will ensure the home page remains relevant and useful as Polykey continues to evolve. We'll close this ticket once we think it has an achieved a deployable and effective version.

[linear]

PRO-207 Revamp Polykey Documentation Home Page

[CryptoTotalWar]

• The Home Page will need to outline the technological makeup of Polykey. This is often one of the first questions devs ask and want to know.

  • What's it built in?
  • How is it encrypted?
  • Is it safe, etc.

  Like if we think of secrets management like a car market, it's like everyone is selling a vehicle, but everyone prides itself on different aspects of the vehicle, such as the interior design, the horsepower of the engine, the pricepoint, the design of the engine, is it hybrid, electric, gas, etc.

We're presenting a new class of vehicles for transport of secrets. We're also providing the digital highways and tolls. We're even providing the deriver's license! The Getting started guide is like driving school, learning how to drive the new vehicle class.

• Provide some media assets.

The Home Page could use less text and more media.

• It's possible that some of the "Theory" will be moved as index pages under the home page and that the home page would be a container for theory pages that introduce new concepts related to polykey's ecosystem. It's an option to consider.

The following are some notes i took of what content we may want to include in the home page.