BizDev Committee Initiative Proposal - Q1 - Developer Documentation

Hello Everyone,

Happy New Year, or should we say year of the Secret Moon :rocket:

Biz Dev Committee has followed up with an initial offer to one of our most loved community members to continue and accelerate his work on the community developer documentation. Technical writing is one of the most important yet tedious initiatives any community faces, and we’re immensely grateful for Schultzie to take this on. He was kind enough to develop the outline, and general timeline (although please dont hold it against him if its more than we thought) to get our documents up to par and in line with other networks. Please reach out here on the forums with any questions or concerns that we can address.

This initiative is going to be funded by BizDev with rollover funds from our Q4 discretionary fund. All accounting of the discretionary can be found in our EOM reports. We forsee being able to cover 80-90% of this total initiative to start, and will be approaching Secret Labs and the Foundation to discuss covering anything our discretionary cannot before bringing any additional asks on chain.

Longer term (outside of Q1) we hope to continue partnering with Secret Labs to identify a long term resource to continue expanding and updating these documents moving forward as our technology evolves. Each update will require someone like Schultzie to comb through documentation, continually verifying its accuracy and updating for any discrepancies.

Summary by Schultzie

If you hang around the dev channels for any length of time, you’ll see it’s not an entirely smooth process for developer onboarding.

With that in mind, I propose a 6-step approach to improving them:

  1. do quick repairs on the docs - make sure links work, nothing is immediately incorrect, etc.

  2. go through the active dev docs (getting set up, creating nfts, etc) with a fine toothed comb via doing them, taking notes, etc. this is going to take by far the longest.

  3. do a thorough analysis of the docs - all cli commands are accurate (and consistent against external sources)

  4. coordinate internal Secret tooling

  5. create a “How to Port your dApp from Terra to Secret”

  6. align Secret dev docs with external cosmwasm dev docs

→ Juno

→ Terra

→ whatever else, if they have it

The Problem

The developer documentation is insufficient. The biggest pain point for developers is the initial onboarding, and there are 2 aspects to this:

  1. strong documentation so developers know how to get started, and get building fast

  2. a strong community that’s there to provide help

I’m not going to address point 2, other than to say Reuven does an outstanding job while also juggling all of his other responsibilities.

However, for point 1, there’s work to be done. See Near 0, LearnNear 1, and Cosmwasm 2 for a few examples of great documentation. I cannot emphasize LearnNear enough. Developers are paid to take courses, and have access to instructional help. That’s crazy.

…but we’re not there just yet.

In the mean time, point 1 can be addressed and attempted to be brought in line with competitors.

The Solution

I want to emphasize that this is a long-term project, with many milestones. There are 3 “short-term” milestones, and 3 “long-term” milestones that are broken down by priority levels.

Short term

These are milestones that can be completed within a single quarter, at this time Q1 2022.

  1. Do quick repairs on the docs - make sure links work, nothing is immediately incorrect, etc.

Some of this has been done already 35, but it’s clear that more attention needs done from a quick pass perspective. This is intended as a stopgap solution. Get in, so that while working on 2, incoming developers are in a better state.

  1. Go through the active dev docs

This is the bulk of the short-term work. It will include going through every single step on all tutorials provided on https://docs.scrt.network/ and Figment Learn | Secret, including fixing and improving upon them. Note that I don’t think figment currently accepts direct fixes, so this will be more involved.

I believe doing every tutorial is paramount to a job well done here, as reading over and reviewing the documentation isn’t the same as executing every command provided.

  1. Do a thorough analysis of the docs

Finally, this will include comparing the documentation against source documentation, such as gaiacli. With Supernova, much of the cli has been updated and so the documentation is no longer correct. This documentation either needs to be reviewed, re-written, or purged completely. For much of the documentation I don’t see a ton of benefit to keeping what amounts to a copy & paste of the source docs, with gaiacli replaced with secretcli.

Long Term

These are long-term projects that will likely need to be updated on a recurring basis. These are loose project ideas that can be expanded further, and all would come with their own proposals.

  1. Coordinate internal Secret tooling

There are a ton of tools that have been built around Secret that aren’t in a unified location for developers to quickly access. These should be coordinated, and documented. Explain how to use them, why to use them, etc. As an example, why is Griptape 6 not referenced?

  1. Create a “How to Port your dApp from Terra to Secret”

We need more developers. Why not invite those from Terra and other ecosystems to port their dApps, but private?

  1. Align Secret dev docs with external cosmwasm dev docs

→ Juno

→ Terra

→ whatever else, if they have it

This is a continuation of 5, in a sense. Create documentation that ultimately amounts to “here’s how to make your dApp work on Secret”.

Resources Required

This is a serious undertaking, that frankly, would be best served by a team of engineers and writers. For the purposes of this proposal, I’m going to outline the hours required for the short-term goals, but I’m leaving the long-term goals available for others to take, for the benefit of the ecosystem.

schultzie | Lavender.Five Nodes

- 8 years experience as a software engineer

    - Authored uncountably many technical and architectural documents, including creating the [Web Map Specification](https://developers.arcgis.com/web-map-specification/) which standardizes 2D maps across all ESRI products and the US Department of Defense

- Validator on more than a dozen networks

- Member of the Secret Network Infrastructure team

- Member of the Secret Network Support team

Hours for part 1: 40

Hours for part 2: 200

Hours for part 3: 40

Timeline

The following is a rough expectation of timeline, assuming the proposal goes through the week of January 3rd, 2022:

  1. The initial pass will take up to 2 weeks, concluding January 15th

  2. The thorough dev docs will take roughly 2 months, concluding around March 15th

  3. The final pass should take another 1-2 weeks, concluding by April 1st


8 Likes

A quick question regarding process, what is a ‘BizDev Committee Initiative Proposal’? It’s not posted in the governance sub-forum so I assume we’re not talking about a signalling / spend proposal for the Community Pool?

How is it decided that the proposal goes through? Vote by the BizDev leads I assume? Is this post confirmation that this proposal is accepted?

Very happy to see work being done on the Dev Docs! Hope we will be able to find more talent for this in the near future to ramp up these efforts.

1 Like

Hello,

Patrick reached out to me on Discord asking if this proposal to further the developer documentation was something I would be interested in getting involved with. I’ve been speaking with some team members over the past couple months about helping with documentation, so this is project is a good opportunity for me to get more involved and put my skillset to use for the Secret community.

I’m not familiar with how this will work (being my first time contributing at this level), but to my understanding someone (schultzie) is taking this on and is looking for some help.

I’m your help.

1 Like

Hey Pmeucke,

Correct, this is not a signaling or funding proposal.

Proposal may not have been the right choice of words. The intent of this post is to get feedback on the content of the initiative that Schultzie will be working on. It’s not open to voting as much as it is to feedback. As of right now, unless we hear otherwise from schultzie + slabs + foundation, we’re not planning to hire any additional resources beyond him (for now).

Other initiatives (that will require funding if discretionary is fully spent) will be posted with ample time to allow the community to give input on direction/scope of the initiative and will vote on chain. In this case, we have the funding to move forward and want to ensure we capture everything the community wants done within the documents space.

Hey, it might be more accurate to think of it as a RFP that I’m responding to from BizDev. This is a proposal written in the context of me providing a service to/for BizDev.

I would absolutely be interested in you joining the team. To what capacity are you interested in tagging in, with regards to points 1-3? From what I’ve seen of your current work, you’d be more interested in the copywriting aspect of it (for lack of a better term), is that correct?

2 Likes

Alright good to hear. I can tag in point 1 and point 2 (most interested in this one). On the copywriting / editing side of things I can always work on making the docs more readable / easier to digest.

Hey,

I am in a similar position as @StoicNorth and had some conversations with Bizdev and the Foundation to help on the Developer onboarding docs. Some People mentioned it would be good for a newcomer to follow the documentation and see if everything is complete enough and working, still open to work on this. If you need help along the way you know where to find me @dylanschultzie , happy to help more on the development side of things as i get more familiar with the network.

1 Like

Hey @ertemann,

I’m planning on just starting working through the docs from scratch and working to improve them. When it comes to Rust I have zero experience to be honest, so it will be a good learning experience + might ask you for some help.

I’m just going to start working on this and adjust based on feedback I get.

@dylanschultzie Do you have a preference for how to about making suggestions / changes / making notes? Will be using Google Drive docs until further notice.

I went ahead and improved the copy of the “General Overview” portion of the docs: General Overview - Google Docs

There is a lot of room to improve it further such as adding more headings / sub-headings + internal and external links.

@dylanschultzie I guess this would just fall under priority #1.

I’d say go straight to making PRs, tbh. We can review each others work for verification.

2 Likes

ok! I’ll just go straight to doing it that way.

Thanks everyone for the collaboration on this, looking forward to the outcome.

Happy to announce that the process for phase one has begun! Thanks Schultzie, StoicNorth, and Ertemann for stepping up to make this community a better place.

Interested parties can follow along the progress here: Developer Documentation Revamp · GitHub