Notes from Holochain RSM documentation audit

--- tags: documentation, rsm, developer experience --- # Notes from Holochain RSM documentation audit ## HDK3 docs * A lot of noise in the left sidebar from imported crates. * Needs documentation at root of crate. * What should go in here? * Welcome to this thing * Information from [hdk readme](https://github.com/holochain/holochain/tree/develop/crates/hdk) * Point to core concepts * Comprehensive understanding of "what's going on?" * how do I structure a DNA? * how do I structure a zome crate? * what does serialisation look like? * what is a zome actually for? * easiest / most idiomatic way to get everything done * entry defs (I'm thinking the structs + `entry_defs!` macro are most idiomatic) * zome functions * host calls * required/optional callbacks, esp validation * I feel like https://github.com/holochain/holochain/blob/develop/crates/hdk/README.md is confusing and also out-of-date. It could give idiomatic examples first, then move into alternatives. * When is this crates.io / docs.rs issue going to be sorted? what are the blockers? * Quality audit * Host fn macros are fairly well documented, but some give too much or not enough info, and leak the stuff they're supposed to hide, e.g., `agent_info!`. Not the end of the world, just spit-and-polish. * `create_entry!` could give a bigger context to what app entries look like -- kinda unclear. * `create_link!` -- there's a lot of stuff about CRUD and I'm not sure why. Could be cleaned up heavily; reads like a comprehensive guide to links (which we also need, but not here). * `emit_signal!` isn't documented. * `get_details!` talks about the need to disambiguate entries with similar content, but I thought that wasn't necessary anymore thanks to the new way CRUD works. I guess it depends on _why_ you'd need to disambiguate now; there aren't any reasons given though. * Light on links/references to other types/definitions. * Re: prev point, the use of macros for host functions really hampers Rustdoc's built in type linking, cuz everything is an `expr`, not a type. * Generally some cleanup needs to be done -- lots of `@todo` comments, kinda wordy or not wordy enough. Not show-stoppers though. * `@see` refs aren't automatically linked. * `hash_path` and `anchor` documentation could be expanded. * Host functions duplicated in their own modules + the root of the documentation is confusing. There's also no documentation for them as modules; it only shows up in the root. Important types don't appear at the root, and given that everything is a macro, you have to go hunting for those types. * Empty modules with documentation for the guest callbacks is a great opportunity to document some otherwise invisible things. * `Error` could use some documentation -- how do we use/return errors in our own zome functions and guest callbacks? ## Admin and app API docs * Well documented, but will need to be published somewhere. It's part of `holochain` crate; is that a problem? too much noise? * Could go more into detail about exactly how to serialise a request object, esp with `AppRequest` which has less info than `AdminRequest`. JS examples would be wonderful. Show how this gets bundled up in a `WireMessage` that works like a JSON-RPC message. * [holochain/holochain-conductor-api](https://github.com/holochain/holochain-conductor-api) will probably want matching documentation * how to keep it in sync? * Maybe it should just point to the rust docs. * TsDoc looks like good docs generator. * Again, need comprehensive documentation, incl 'entry-point' overview (I suspect this should go in `AdminRequest` and `AppRequest`) ## Getting started and building stuff * Migrate installation guide to dev docs site * how to keep in sync? * How do I... * scaffold? (you don't) * compile? (https://github.com/holochain/holochain/blob/develop/docs/build_tutorial.md) * test? * run? (https://github.com/holochain/holochain/blob/develop/docs/build_tutorial.md and/or https://github.com/holochain-open-dev/holochain-run-dna) * `dna-util` comprehensive documentation (https://github.com/holochain/holochain/tree/develop/crates/dna_util) * DNA manifest format documentation needs to be written. * hApp bundle manifest format documentation needs to be written once it exists (not set in stone yet; need to use admin API). * When will the binaries be available via Holonix without any special steps? ## Using the conductor * Command-line documentation (available at root readme of `holochain/holochain`) * Config file documentation not available? * How do I... * get an app running and talk to it? (using a sample JS script and/or holochain-run-dna; see also https://github.com/holochain/holochain/blob/develop/docs/build_tutorial.md) * test an app? (Tryorama documentation) ## Existing documentation * Remove all tutorials and guidebook * Set up site for deprecated materials * Make sure things are 'not wrong' * core concepts * glossary * Migration guide; where should this live? When should it be retired? ## Prioritization * New Developers Get documention they wantand : * Old docs not wrong * Retire obsolete stuff; make it clear that it's retired * Fix discrepancies in non-obsolete stuff * Comprehensive * Get started w/ minimum of fuss # Prioritization Stages and Tasks 1. Bare minimum of support for hApp devs * Fix errors in core concepts and glossary * Retire obsolete materials * tutorials * HDK 2.0 link * guidebook * Check accuracy and comprehensiveness of other resources and improve access to them (Core request for Paul's review of any HDK and Holochain_types that app devs will interact with; min doc every component for basic understanding) * installing Holochain binaries (Watch V1) * DNA building (Watch V1) * HDK3 + holochain_types reference (Stablizing will happen after LF) * host fn macros are difficult dev experience because args and return values aren't linked * Documentation missing for `emit_signal` -- anything else? (comb-the-docs spike?) * Guest callbacks need documentation; stub files are great places to put that * HDK3 guide (readme) and serialisation guide -- dense information, suspect they're out-of-date (Checkin after Stabilization of HDK3) * Admin and app API reference -- buried within the `holochain` crate; can we make them more discoverable? * migration guide (Ask specific questions) * Tryorama documentation (Shifting to Holo host team, will include readme updates--not fully functional for Holo, currently; downloading from Michael) * Command-line references (Paul to make more accessible) * Create missing resources (core team) * Conductor config file format reference * hApp bundle file format reference (spec not ready yet) * DNA JSON file format reference * Give people a notice about current quality and future plans 2. Quality and accessibility improvement * Tighten up quality of reference materials and other resources * installing Holochain binaries * DNA building * HDK3 reference * HDK3 guide (readme) and serialisation guide * migration guide * Tryorama documentation? * Bring all external resources (except auto-generated reference documentation) into developer.holochain.org * Publish auto-generated reference documentation on docs.rs 3. Making it awesome * Rewrite core concepts * Create materials for entrepreneurs * Rewrite tutorials 4. Making it really really awesome * Create a new guidebook of sorts * Create a collaborate-able pattern library ---- Notes from Paul/Jarod convo 2Dec2020 - once HC RSM hits Holonix in a serious way (replaces Redux or wait until RSM Holonix starts showing up on holochain.love--> that is when we have to be 100% RSM) - push towards numbered release of holonix - Redux doesn't have good dev tooling, RSM works better - 5 people daily downloading Redux from github https://crates.io/crates/hdk (?how much of that is internal) - Notice on Github? - Change quickstart guide--how to get RSM - how to coordinate the moving of everything - - Near term - Deprecate doc, but still have - Quickstart to slow start ---- # Thinking out loud re: transitioning to RSM Paul, 2 Dec 2020 So I'm making plans for refactoring the documentation for RSM. The biggest thing is that **I want it to be a clean transition for existing and new hApp devs**. This is one half _coordination/timing_ (making sure things that should happen at the same time do happen at the same time) and one half _resource allocation_ (I've got a bunch of my own work to do, but I'm hoping the core devs will also have time to skim through the new Core Concepts to make sure there's nothing wrong there). I'll leave resource allocation to the POs; what I want to talk about with y'all is coordination. Here's what I think the plan should be... ## Right now (or ASAP) Holochain RSM has pretty much leapfrogged Redux and the people I've talked to say we shouldn't be telling devs to use Redux anymore. So my plan is: * Redux documentation will live on a legacy documentation site. * Dev docs will have **no Redux-based contents**. * Content on dev docs will not be complete but will be correct. * Revised core concepts * Revised glossary * Revised ~~quick~~ _slow_ start guide ;) * Installation w/ Holonix * Setting up dev tools * Compiling a DNA * Running a DNA * No tutorials * No guidebook * Pointers to helpful resources * HDK readme * Migration guide * Devs can access the HDK docs via the command line; that'll be part of the slow start guide. ## Near term * The HDK docs are published to docs.rs, and then I can link to it from the dev docs. I think it also requires documentation of the guest callbacks. * The conductor admin API is documented and published on docs.rs. * The HDK readme is updated and maybe even copied to the dev docs. ## Slightly further out Once Holochain RSM is available in Holonix we can start pushing it to holochain.love, and we can turn the slow start guide into a quick start guide! ## Long term * I don't think we'll rewrite the tutorials around the core concepts; instead, we'll lean on [Holochain Gym](https://github.com/holochain-gym) courtesy of Guillem and co. * Rewritten core concepts * Rewritten guidebook * Pattern library * Resources for non-dev creators -- entrepreneurs, etc * hApp bundle spec reference * Conductor config reference * Command references ## One last note Tryorama scripts in the wild that have been auto-generated by `hc init` are already broken, because the semver target in the generated `package.json` is `^0.3.0` and we're up to `0.4.0` now. So it really behooves us to leave Redux behind.