cosmos / advocates

Cosmos Advocates

advocates

The Cosmos Advocates repo tracks doc issues, feature ideas, and other collaborative doc efforts. The Cosmos Advocates people care about developer onboarding of Cosmos technology, documentation efforts, and cross-team coordination.

Reporting doc issues

For general outstanding tasks for docs, create an issue here in cosmos/advocates repo.

When you identify specific technical errors, create a doc issue in that project repository. See the working list of docs for the primary content owners and links to the published documentation and the repo or repos. Technical code maintainers for projects are mandated to update documentation, like Cosmos SDK.

For all issues, help us out. Provide helpful details of the doc that requires attention, including:

• topic
• links
• context
• version
• screen shots
• other relevant information

Issue triage

As we scale our content teams, issue triage is a fluid process that we're still working out. Thank you for your patience. Thank you for caring.

• For Starport docs, tag @barriebyron
• For Cosmos SDK tutorials, tag @toschdev
• For Cosmos SDK docs, tag @barriebyron and she'll try to find out what to do next.

Questions

Questions? Please ask. Let's elevate each other.

advocates's Issues

Add the docs roadmap

Connecting two Starport chains with hermes relayer

A blog post demontrating how to connect two Starport chains using the hermes relayer

swagger issues

• default version of gaia should be v4.0.4
• default base URL should be rpc.cosmos.network
• rpc.cosmos.network needs to be updated to be able to serve over https
  • currenlty the cosmos.network/rpc site is served over ssl so any requests that take place from here also have to be ssl. Otherwise we need to be able to serve the /rpc site as http and then query the rpc.cosmos.network using http (and should set it as the default option)

Currently all test requests result in TypeError: Failed to fetch until these issues are fixed.

Go Relayer Tutorials

• Local <> Local
• Local <> Remote (starport to the hub)
• Remote <> Remote (hub to iris)

authz tutorial

i'd like to see a demonstration of authz such that a user can separate their voting capabilities from their bank. I need to look into what the exact steps are to make this happen with authz but it's likely to be the most common initial use of the module and there should be special attention paid to ensuring it's easy to understand how to do this. Likely it should involve utilizing keplr to leverage the different key capabilities in an easy to understand way.

docs: restructure, ensure accuracy in Starport docs

@barriebyron is working on Starport docs for v0.14

• organize by area of functionality
• remove unsupported features
• prevent duplication with Cosmos SDK content

Details in ignite/cli#806

Cosmos SDK and Tendermint glossary

Mission: Develop a single source of truth glossary for Tendermint and Cosmos SDK.

Because a published glossary exists, we will focus on improving the published glossary https://cosmos.network/glossary

As of April 2021, Stargate new website is live but this cosmos.network glossary is still v1 and on the design team list. Curiously, the glossary is sourced in two places for two purposes.
See Cyrus comment in this PR

broken link detection in core software repo CI

For the SDK, Tendermint, and a handful of other core repos, we should have tests that fail when links are broken. At very least for relative links within the same repo.

Create a progressive narrative for sdk tutorials

interplanetary life

le petit prince style tiny planet existence

could level up like katami damacy

• STAGE 1
  • In the beginning there is just a planet and a token
  • starport command with fun token name
• STAGE 2
  • You want to invite someone to your planet so you make your planet public
  • compile the binary
  • send the binary to a friend
  • upload the binary to a server
  • run the binary from the server
  • give your friend the IP address of the server
  • tell your friend to generate an account
  • send your friend tokens to that account
  • let your friend send tokens to someone else
• STAGE 3
  • You want more friends and you want them to collaborate
  • You add the governance module
  • Maybe you invite more friends to actually operate the public planet as validators?
• STAGE 3
  • You want a custom feature / you develop it locally
  • you want your planet to write letters to each other instead of just sending money all the time
  • you're bored of capitalism lol
• STAGE 4
  • You want the custom feature included on the network with your friends
  • You use the upgrade module
• STAGE 5
  • You want your planet to start communicating with other planets
  • You start by sending tokens to another planet
  • default IBC
• STAGE 6
  • You want your planet to start sending letters to other planets
  • You make a custom IBC type
• STAGE 7
  • You want your planet to start taking part in an interplanetary council
  • They will need interchain accounts that rely on the governance module

You are now a sophisticated interplanetary civilization

feat:canonical word list to ensure consistent terminology for all content

Our developer funnel and Developer Portal will onboard devs to grow the Cosmos ecosystem.
With so many content developers inside Tendermint and elsewhere in our ecosystem, we realize that we use key terms in a variety of ways. To ensure consistency and build trust in the community, we are creating a canonical word list that defines style guidance for ecosystem terms and other frequently used words.

For now, the word list is organically growing in this Word List Cosmos spreadsheet. Follow the capitalization and case as shown for each term.

• The word list includes selected Cosmos Developer Portal terminology for use by Tendermint and B9 Labs as we build out the portal and other technical content.
• This word list strives to be the single source of truth for all terms in our ecosystem.
• To add or update the list of terms, add a comment to his GitHub issue or contact @barriebyron (Tendermint), @christina (Tendermint), or @Citlali (B9lab).

Questions? Please ask.

For other technical content style guidance, see Cosmos style guide, tone of voice (accessible to all) and internal Tendermint Technical content style guidance in Notion.

feat:in-depth article on Cosmos SDK events is good candidate for article

from @okwme

content from Ethan Frey that is apparently one of the most in-depth articles on events. I thought it might be a good candidate for an easy article to add to the tutorials.cosmos.network page, what do you all think?
https://github.com/CosmWasm/wasmd/blob/master/EVENTS.md

cosmos-sdk docs broken from search

if you google into the docs, most of the links that show up first are broken bc they link you to ‘master’ and not the latest version. for example: https://docs.cosmos.network/master/modules/upgrade/ vs https://docs.cosmos.network/v0.42/modules/upgrade/#upgrade

maybe we can redirect master to the latest version in order to not lose the seo?

Where is gaiacli ?

Blog post talking about what changed with gaia, now there's only one gaiad no more gaiacli. Some people might still find confusing so this might be helpful, also can help in case people come across old documentation that still shows gaiacli but will help them realise that gaiacli is gone.

Docs Todos

This issue is a list of the major documentation ToDos for each project.

Cosmos SDK

• Write Scaffold Guide (using-the-sdk section)
• Write follow-up "Adding Modules" guide (using-the-sdk section)
• Finish simulation docs
• Update module specs (e.g. gov)
• Write migration docs (using-the-sdk section)
• Improve ocaps docs
• Tokens docs (denom, bech32 prefixes, cointype)
• Proof of Stake overview doc
• params concept doc
• Write "Validators" basic concept docs
• Validator set changes overview doc
• Improve context
• Write "deploying your chain" doc
• Write "upgrading your chain" doc
• Turn "Store" doc into "Store" section, with one doc per store type
• add example of how people could use their own key types

Tutorials

• Upgrade hello-chain
• New landing page - allinbits/design/issues/265
• Add IBC tutorial (potentially as section of nameservice)
• Typescript basic client tutorial (probably an SPA client of nameservice)

Gaia

• Update to new theme
• Read through of all docs and update/improve what needs to be
• Rework landing page - related to allinbits/design/issues/182
• Rethink role of swagger docs (is it a gaia rpc endpoints list, or a generic cosmos sdk rpc endpoints list)
• Add delegator intro section (staking section?)
• Add governance section
• add section on pruning

IBC

• Write concept docs for the main IBC concepts (Connection, channel, handhsake, ...)
• Write SDK IBC implementation guide
• Move generic docs (spec, concept docs, ...) to a repo outside of cosmos github org (ICF?)

Tendermint

• New landing page - allinbits/design/issues/266
• Update organisation/architecture of the docs
• Read through of all docs and update/improve what needs to be

basic readme for this repo

I'd like to start sending core teams here when they find an outstanding task with docs. If we could have a very basic readme that tells them how to add issues and how they're triaged that would be very helpful.

Improve IBC docs on ibcprotocol.org

We need a resource to answer all the most basic questions about using IBC before it comes to deep dives in specs. This website should serve this purpose but currently only has the deep dive spec information.

The website begins doing this with a FAQ section that might need to be more prominent and also needs to have more content in general. @ethanfrey had some concrete requests that maybe could be tracked on this issue.

identify knowledge entry points for new users

As I collected links to learn about: Cosmos SDK, Interchain Foundation, and blockchain in general, I realized that other new users are also collecting links.
For docs to be valuable, three things need to happen:

1. users can find the information
2. users can successfully consume the information
3. users can return to the information

The goal of this resource list addresses points 1 (discovery) and 3 (know how to return).

Rough working list in the Learn about Blockchain and Cosmos google doc so we can all access, comment, contribute, and enjoy.

Scope excludes maintenance. Let's use the current GitHub issue process in place for content maintenance.

cosmovisor demo tutorial

I'd like to see cosmovisor widely adopted by validators. In order to gain their trust in using the codebase features like making backups to the data directory are under way. In order to further demonstrate that it is safe and easy to use I would like to have validators try it out before the next upgrade. Typically validators would participate in a testnet in order to test out new features. However it's traditionally been hard to get validators to participate in these. As an alternative I'd like to create the following user story:

• I'm a validator who doesn't have the capacity to coordinate participating in the next hub upgrade testnet but I want to understand how cosmovisor works so I can evaluate whether I will configure my infrastructure to use it.
• I go to github.com/cosmos/cosmovisor-demo and read the README.md
• I learn that I should be able to run the following commands:
  • git clone github.com/cosmos/cosmovisor-demo
  • make install
  • demogaiad init test --chain-id test
  • demogaiad keys add my-val-key
  • demogaiad add-genesis-account my-val-key 1000000000stake
  • demogaiad gentx my-val-key 1000000000stake --chain-id test
  • demogaiad collect-gentxs
  • demogaiad start
• in another terminal window i should be able to do the following actions
  • make a gov proposal for an upgrade that references another release of the same repo
  • have the gov module configured so that the vote only takes 5 minutes
  • make sure cosmovisor is enabled and set to autoupdate
  • wait the 5 minutes and watch the upgrade take place
• it should work with a variety of common validator settings and configurations
  • get feedback from some validators about this
• as much as possible should be pre-configured and/or put inside of a bash script or make file
  • we want the user to understand what's happening and why but not be too tedious

Create a list of all doc properties

actually there are tons