# Dev docs notes Matt/Thomas/Paul 15 Dec 2023 * Thomas: diagramming -- in the dev training too. They had one good visual for cap grants, but that was it * Matt: Rust crate documentation disjointed, you'd have to click through every crate to get top-level docs. Some useful things; * Thomas: rustdoc readability not that great * Matt: part of the issue is Rustdoc format * A lot of things aren't adequately covered * Diagrams: what would be helpful? * Thomas: UML diagrams * Sequence diagrams, activity, deployment * Visualisation of entire Holochain engine, 3d, follow workflows through the core * Component diagrams * high-level: how do you deploy? * Guidebook made a lot more sense to Matt * Top-level categories * Discovery * Examples: * How to use links in creative ways, introduce paths in HDK, point to Rustdoc, talk about things you need to think about when using paths (e.g., limitations in validating paths) * More encyclopedic, not use-case-based. few examples are just fine * Best practices for architecture * Why does the scaffolding tool make the decisions it does? What patterns is it baking in? What are the tradeoffs * System documentation * e.g., components involved in a workflow (sequence diagram?) * Sometimes trying to illuminate workings of the core can piss people off because changes. Thomas suggests an internal discussion of how core is documented/works -- not for public consumption tho * knowledge of internal workings is helpful if you want to be a core contributor * What one thing would you have wished for? * Matt: code examples, linking into the Rustdoc from a structured page * higher-level understanding of a thing's purpose * here's how you use it * patterns (front-end too! e.g., UX for incomplete data) * Thomas: learning by example, more examples he had the more he learned. Would've been nice to have tutorials to implement x or y * also sequence diagrams :) * scaffolding tool really helped * something that runs out of the box * Barriers to contribution * Matt: concerns about writing skill * Paul's thought: PRs allow for editorial review; a lot of valuable insight could be lost for fear that it's 'not good enough' * How do you actually contribute to Rustdoc and Dev Portal? * Thomas: as devs write apps, would be useful to share what they've discovered. Wants to give back. * Paul's question: where? * Matt: part of the challenge is learning Rust, distributed systems, and Holochain at the same time, as a consequence it's hard to know what bits of knowledge belong in the official docs * Matt: is there room in the devdocs for a random smattering of info? * having it in a community wiki makes it hard to discover * Thomas: linking from glossary to other resources? * Thomas: biological metaphor documentation? another lens on the system that would be helpful for some people. Matt suggests "background on naming" page * Follow-up: map out topics * Matt: CC is a lot of prose. Turn them into the structure to plug other resources into * alternative structure: journey of building a hApp * one thing to map out: coordinator vs integrity -- what to put where?