---
# System prepended metadata

title: Dev docs notes Matt/Thomas/Paul 15 Dec 2023

---

# 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?