Hats Protocol Documentation Feedback

Hats Protocol Docs are a key resource for users to learn about and start using Hats. Use this Topic to provide feedback on the docs and contribute to their ongoing maintenance & improvement.

All feedback is welcome.

1 Like

@davehrlichman The Hats Protocol Docs page is awesome, great work! Layout is intuitive, content is clear and actionable, and the docs contain most of the info I’d expect to see on a documentation page.

Below is my feedback based on the questions you sent in Telegram. Obviously feel free to disregard any of it and/or follow up with clarifying questions.

For the stuff that you do like and want to add, I’m available to help with content creation, act as a sounding board, and help with documentation management more generally.

Introductory pages & onboarding flow

  • Welcome to Hats Protocol page
    – Under the What Are Hats? section, move the last paragraph (hats are programmable, revocable, legible roles…) to the top. This will help contextualize what hats are conceptually, then the next paragraph (Hats are represented onchain…) about what are more specifically).
    – Under the Why Should We Use Hats? section, add a punchy intro sentence that is gets at the core of “why” and is easy to remember. For example, Using Hats, organizations can create and manage roles that unlock the power of decentralized work.
  • Getting Started with Hats page
    – I like the breakdown of getting started with Hats in one of two ways.
    – It could be helpful to add sections for specific user personas (similar to the existing “For Developers” section). e.g., “For Governance Facilitators”, “For Community Managers”, “For Guilds”, “For Project Teams”, “For Treasury Management”. You could even link to the Wiki’s Hats Tree Templates page.

Navigation feedback

  • In general, the navigation and layout is super straight forward and clear.
  • My only piece of navigation feedback is to add a Quick Start page in the intro section.
    – This page is designed for people who know their way around Hats and want a one-stop-shop for key actions, user guides, and resources.
    – To start, you could just link all of the action-oriented pages in the existing docs. Then add to it over time based on user feedback.

Information you were hoping to find but could not

  • Glossary & FAQ pages
    – I started aggregating terms and questions on a Google Sheet, based on conversations and feedback from the community (h/t @enicole & @JafCR)
  • A User Guides section for specific use cases and user personas
    – The idea here is: “As a , I want Hats Docs to have a self-service guide with step-by-step instructions, so I can use the Docs to implement my using Hats.”

Additional improvements about their look or contents

  • This is a personal preference, but I also like to see more visuals (e.g. instructional gifs, screenshots, visualized workflows, visualized concepts).

@davehrlichman I put this Google Form together as a POC for sourcing glossary term requests, FAQ questions, and general documentation feedback. You can edit it here.

Responses are captured in this Google Sheet.

Again, this is just a POC and I won’t share anything without syncing with you first. But if you like this from a process perspective, I’m thinking here are some potential short-term next steps:

  • Iron out information flow process (information capture form > term definition & question responses > updating the Docs)
  • Nail down Submission Form questions
  • Determine if Google tooling is the best option or if something like Typeform is better

Other things I have in mind for the medium term:

  • Operationalizing this in terms of well-defined roles (e.g. spinning up an “Info Management” Admin Hat for the protoDAO)
  • Implementing the entire Info Management function using Hats Protocol (e.g., token-gated access to Google Form, Sheet, and Gitbook)
  • Structuring the information capture, curation, and synthesis so that we can pipe it into a Hats-tuned LLM model for better self-service

Lmk your thoughts, comments, critiques, etc. Happy to coordinate sync or async over Forum/Telegram. Cheers!

1 Like

I fully agree with all points @moreReese mentioned here. They are on point.

wrt the Charmverse docu:
Great job with the Roles section. It makes very clear the progression path and sets clear expectations for each role. It doesn’t mention what exactly is a “season”, but in general the idea is clear.

All documentation is very well structured, and put in a well-thought order.
Demos are :fire: . Can’t wait to see a v2 loom demo video

Two extrimely minor details to correct

1.Section: “Hats Protocol Public/Hats v2.0 announcement”
Sub-section: tl;dr
it says: “Protocol v1 is now stable after a __________”
I’d presume you wanted to point at the “Stable Protocol v1” section below.

  1. News and Updates: incorrectly mentioned v1.3 rather than 2.0
    put a suggestion in charmverse directly for testing :slight_smile:

Thank you @moreReese and @Jaf! Great feedback. I incorporated these suggestions, most prominently in the new Quick Start page and the new Glossary & FAQ page. LMK what you think and we’ll keep making this better!