Documentation and users

[Mirko-von-Leipzig]

Documentation and keeping things ordered is currently a bit confused in our repo. We have several places with redundant information, and therefore also often outdated information. I believe part of the problem is that we're conflating several categories of people and attempting to satisfy them all.

I'd like to

1. discuss what we're documenting where, and for whom, and
2. make some suggestions to hopefully simplify and structure things

Kinds of "users"

We somewhat cater for the following groups:

1. Developers on this repo
2. Node operators
3. Infrastructure operators (e.g. explorers, wallets etc)
4. dApp builders
5. People researching and/or interested in Miden

Current scope

We have semi-independent documentation in the following locations

• root README.md
• crate README.md
• proto definitions
• /docs and a script to serve which I believe is just empty?

The root README.md largely targets node operators. Subsets of this are then repeated in some crates.

The gRPC API is documented in both the proto definitions, as well as the specific crates.

Suggestions

We don't really have publicly useable crates. They're large just a code organisation mechanism for the node and faucet binaries. I think we should simplify all of their readme's to just give a one-liner summary of what it is, and then link to the main readme. These are effectively internal-only imo.

Separate the node operator docs from the developer docs. Right now the repo homepage is largely for node operators but its awkward because that's also the landing page for our developers. I suggest we treat the main readme as a landing page, move the operator docs somewhere else and just link to them. The landing page would basically summarise and link to the various entry-points i.e. bin/node or /docs/* etc, along with the usual license and disclaimers.

The node operator docs could move either to docs/operator/* or become the bin/node/ readme (which is currently barren).

I'd like to add developer docs to docs/dev/*. We don't have anything there yet, but I like the idea of architecture (example). This would also be the place to add style, conventions etc.

proto

I think until we've figured out a good enough automatic or manual solution for documenting these properly, I would suggest we:

• only document in one place i.e. in the .proto files, and
• simply link to the appropriate file(s) in the readme

I'd also still prefer to simplify this by only keeping a single proto copy and generating the rest the build.rs, but that's a separate argument :)

Changelog

Could we define what we consider to be part of our public API? As in, what should(n't) go into the changelog and what constitutes a breaking change. This doesn't have to be perfect; just so we're aligned.

My perspective is that our "public" interfaces are:

• RPC component's gRPC API
• miden-node configuration and CLI
• miden-faucet configuration and CLI
• protocol related changes in behaviour aka network changes

Notably, this excludes the store and block-producer APIs.

[bobbinth]

We don't really have publicly useable crates. They're large just a code organisation mechanism for the node and faucet binaries. I think we should simplify all of their readme's to just give a one-liner summary of what it is, and then link to the main readme. These are effectively internal-only imo.

Largely agree, though I do think we have a couple of publicly-usable crates. Specifically, I think of the miden-node and maybe miden-rpc-proto as something that others may want to use directly (miden-node for operators and miden-rpc-proto for developers).

Separate the node operator docs from the developer docs. Right now the repo homepage is largely for node operators but its awkward because that's also the landing page for our developers. I suggest we treat the main readme as a landing page, move the operator docs somewhere else and just link to them. The landing page would basically summarise and link to the various entry-points i.e. bin/node or /docs/* etc, along with the usual license and disclaimers.

Also largely agree, though I do think miden-node README should be "presentable enough" because it also is something that will appear on crates.io (i.e., I'd make it more than just a one-liner description).

The node operator docs could move either to docs/operator/* or become the bin/node/ readme (which is currently barren).

I think here we have 2 goals:

1. Make README for bin/node presentable enough (as mentioned above) - and so, I'd put a bit more "meat" into this file.
2. Prepare node documentation for inclusion in the general Miden documentation repository (i.e., miden-docs). This would basically mean that most of the docs go into the docs directory which then gets cloned and included into the overall documentation site. So, having docs/dev, docs/operator etc. makes sense to me.

I think until we've figured out a good enough automatic or manual solution for documenting these properly, I would suggest we:

• only document in one place i.e. in the .proto files, and
• simply link to the appropriate file(s) in the readme

I think this is fine for now. I would like, at some point, to have a comprehensive documentation of the public gRPC endpoints (i.e., the ones exposed by the RPC component) - but maybe that's what goes into docs/dev directory.

My perspective is that our "public" interfaces are:

• RPC component's gRPC API
• miden-node configuration and CLI
• miden-faucet configuration and CLI
• protocol related changes in behaviour aka network changes

Agreed on the definition of what's public, but I also think it is fine to include non-public refactorings in the changelog - especially the big ones (e.g., mempool refactoring).

[Mirko-von-Leipzig]

Yeah I agree :)

I'll figure out a way to get there piecemeal; should be able to simply add the /docs without impacting anything else, and improving the node readme. Then once we're happy we can cleanup/standardize the rest of the readme's etc.