Developer Documentation Ownership

Secret Governance
1

The objective of this post is to lay out a plan for the future of Secret Network’s developer documentation (https://docs.scrt.network)

The Problem:

Secret Network’s developer documentation was originally authored by developers at SCRT Labs (back then known as Enigma). It has since been maintained partly by them, and partly by members of the community. However, it has not been maintained actively enough, resulting in inaccuracies, out of date information, broken links, etc. New developers coming into our community and attempting to use this documentation have run into many issues. This is a sentiment echoed by nearly every developer in the community.

The state of the documentation is a roadblock for many of our growth initiatives. As part of Shockwave, our goal is to have 100 new projects building on Secret, onboard hundreds of thousands of new users into the ecosystem, and have multiple applications with 10,000+ active users. In order to do this, we have to onboard new developers. We can do this through initiatives like our 400m ecosystem fund, hosting hackathons, in-person events, and additional marketing. However, when new developers join the community and run into major issues with the documentation while trying to get started, we’re going to lose them. They will likely go to other blockchains like Juno, Terra, NEAR, etc. that have easy to follow, user friendly documentation.

The Solution:

A few months ago, @dylanschultzie proposed a multi-phase plan to improve the documentation, along with @StoicNorth and @ertemann. This was funded in part by the BizDev committee, and partly by SCRT Labs and the Secret Foundation for the final phases. The first 3 phases of this plan have been completed, and the documentation is in a much better state than it was before. However, there are still parts that need to be updated and improved on for clarity. Due to the nature of code development, constant editing is required to stay up to date. Presentation could also be improved on.

@StoicNorth has been doing the majority of the work under this team, but has only been working part time (10-20 hours per week) due to funding and scope of the project. He is a technical writer by profession, and is willing to make this his full time job. I think this would be a great first step to getting our developer documentation in order. If one person working full time turns out to not be enough, we may want to hire additional technical writers as well, and @StoicNorth has stated that he has experience with managing a team.

However, no matter how many technical writers we have working on this, they’re going to need to be able to communicate regularly with SCRT Labs in order to stay informed of upcoming changes and get answers to questions. Ideally, SCRT Labs would delegate one of their developers as a point of contact for the documentation team, and attend meetings with them regularly.

Additionally, a source of funding needs to be determined for these technical writers. As they would be working closely with SCRT Labs to document code that is written by SCRT Labs, many community members have proposed that SCRT Labs fund this effort. However, there are additional sources of funding that could be considered, including the Secret Foundation and on-chain resources.

Summarizing

  • We need at least one full time technical writer working on developer documentation
  • They need to be able to work closely with SCRT Labs
  • We need to determine a funding source

What are the community’s thoughts on this?

9 Likes
2

Strong Agree with all of this

3

@StoicNorth has been a serious asset in the developer docs initiative, to say the bare minimum.

I agree with all points outlined - a full time tech-writer would be a massive boon, and must be integrated with a development team in order to be most effective. Currently we are only able to work reactively, and that’s rarely a recipe for success.

I don’t know what that would look like in practice - would that mean they are hired directly by SCRT Labs so they can work in tandem?

Given that Slabs is currently training/onboarding devs, I imagine the best path forward would be to integrate @StoicNorth in with the incoming devs, and train them as a developer would be trained. This creates a stronger basis of understanding for writing more effective documentation. In addition, it creates a much-needed direct communication channel.

Part of the difficulty with this initiative is the decentralized nature of it. As an offhand example, I’ve been speaking with @assafmo about how best Slabs can integrate a tech writer… Meanwhile, @ertemann has been speaking with @reuven about the same topic. Both of us have received different answers. To be clear, I don’t mean for that to be a damning statement at all, just that communication is difficult across different channels and stakeholders. Direct integration with the team is necessary to bridge that gap.

4 Likes
4

We had another meetup today.

Both funding and timeline seem to be discussed and set. First initiative is to write out the full Table Of Contents and get out a survey to some new developers. Scrtlabs, the dev committee, the SF and the original Documentation team will be having a meetup early next week to scope out the entire TOC.

When TOC is done all single tasks will be taken 1 by 1. Scrtlabs will start dedicating significant time after the upcoming update, a full time technical writer might be an extra option but also the community has to be employed in this effort.

If you want to keep up to date or read the full notes etc then join the “secret university” discord. Secret University

1 Like