The evolution of the Stacks documentation and a new Hiro docs site

Community
#1

TLDR: We will be splitting the Hiro documentation from the Stacks ecosystem documentation over the next month. A new Hiro-focused documentation site will be created. The Stacks ecosystem documentation will be handed over to the community.
​​
​​The Stacks ecosystem has done a lot together. As a community, we came together to keep up with the developer documentation for advancements of the Clarity language, the Stacks blockchain, the tooling, and more. We organized docs days, encouraged and added contributors, maintainers, and reviewers for the docs repository, and established an open communication channel in the Stacks discord.
​​
​
​The ecosystem is growing
​​The Stacks ecosystem is thriving like never before! Thanks to the Stacks Accelerator, the Grants program, independent builders and more, we have a many teams working on tools relevant for developers. Some of these builders already created their own documentation. With all of these folks joining our community, it’s our collective duty to ensure new developers joining the Stacks ecosystem can discover and learn about all the great projects from a wide range of ecosystem contributors. At the same time, we as Hiro, need to advance the documentation for the new and updated developer tools Hiro is actively developing.
​​
​
​The need for a split
​​And this brings us to why we think there needs to be an evolution. Currently, the general Stacks documentation exists alongside documentation that represents Hiro products. This presents several challenges:

  • Hiro’s focus on the documentation around its own developer tools could leave a gap in resources focused specifically on Stacks documentation, and that could lead to outdated or incomplete documentation on the Stacks side

  • There is no ecosystem-wide documentation effort, working group, or roadmap

  • ​​Highly relevant, new documentation sites are appearing but not surfaced well enough to Stacks developers
    ​​
    ​
    ​The new Hiro docs site
    ​​We are planning to create our new Hiro Documentation site (coming soon at docs.hiro.so) that will focus solely on Hiro development tools. It will be open-source, and open to community contribution, although subject to a tighter roadmap set by the Hiro docs team, and beholden to Hiro feature development. Hiro’s docs team will exercise editorial discretion over the Hiro docs, and will communicate regularly with the Stacks community on enhancements to Hiro products and documentation.
    ​​
    ​​This work is estimated to be completed by the end of September.
    ​​
    ​
    ​Next steps for ecosystem documentation
    ​​With the above change, the community can take ownership of the existing Stacks ecosystem docs (minus Hiro docs) at docs.stacks.co. Our initial thought is that it could cover topics such as an explanation of the Proof of Transfer consensus mechanism, mining, Clarity language, and more, but the exact content and scope will be up to you. This site would need to be maintained by the community, and not just by Hiro. Of course, Hiro expects it will participate from time to time as one of the ecosystem contributors, but we will not set the roadmap or agenda, nor will we exercise final editorial control.
    ​​
    ​​Some things we’ve thought about as a starting point for the community’s conversation about this:

  • How can all ecosystem contributors best leverage the documentation for discoverability and education about their solutions in a fair way?

  • ​​Who will help maintain the Stacks ecosystem documentation site from a technical, operational, and from content standpoint?

  • How and who will proactively engage with ecosystem contributors to align on a roadmap?

​​
​​So Stackers - have at it! We’ll be participating in the thread here or wherever else you’d like to continue the conversation about the evolution of the docs!

1 Like
Proposal for Stacks Github changes
#2

Makes a ton of sense! The Stacks Foundation is ready to help here! We are exploring a Stacks Residence program and imagine a docs resident could really be a good fit for helping to establish this cleanly and then setup a process for ongoing maintenance by the community. Will propose in more detail soon :slight_smile:

cc @jennymith

3 Likes
#3

Hey @alex-hiro just chiming back in here, we’ve discussed this here at the Stacks Foundation and have come to the conclusion that the Stacks Residence program will be a great mechanism for getting someone in to support this transition as well as setting up ongoing processes by which the documentation for the ecosystem can be maintained.

We’re finalizing the various ways we can compensate residents and in the next 7-10 days will be opening up applications as well as listing a few more specific ‘open positions’, so to speak. This docs position is high on the priority list with hopes it will be among the first few residents brought in, should the community agree. The process by which residents are selected will be community-driven much in the way grants are today and we’ll be encouraging nominations/referrals from the community as well.

Would you and/or Hiro be able to help us put together a role overview (something similar to a job description) for this? Given Hiro’s knowledge and background, it would be extremely helpful to have your perspective as to the immediate short-term projects to be handled as well as your view of the longer-term responsibilities. From there, we can lead the way on placing this resident!

Excited for this, thanks for kicking this off - the split makes a ton of sense and I think will enable the next evolution of documentation for the ecosystem :pray:

1 Like
#4

Glad to hear! Here is an excerpt of previously published docs lead JDs - this could be a good starting point:

# Responsibilities

- Write, review, edit, & organize new and existing content
- Distill complex, technical topics and turn into easy to understand documentation
- Establish an efficient process for maintaining and updating documentation on an on-going basis
- Actively engage and involve community members to multiply documentation improvements
- ​Analyze, gather feedback, and research effectiveness and impact of documentation to identify opportunities for improvements

# Skills

- Experience with technical writing and editing, particularly with developer documentation
- ​Experience enforcing documentation standards, guidelines and driving best-practices
- Understanding of Markdown/MDX, Typescript, React/Next.Js
- Experience with development tools and practices(Git, GitHub and/or similar docs-as-code environment)
- Ability to learn new technologies quickly
1 Like
#5

We just opened up a PR on the Stacks docs to remove the documentation that will be hosted on the new Hiro site. Please take a look and leave some comments: https://github.com/blockstack/docs/pull/1276.

Thanks!