Magesmiths v3 Documentation: JP+E2T+TW Sync

--- ###### tags: `gutenberg-galaxy` --- # Magesmiths v3 Documentation: JP+E2T+TW Sync Monday June 20, 2022 1. Scope, triage, prioritization of the Magesmiths tasks. Each task should be associated to a particular Magesmith to have a lifeline. 2. Reference: other outstanding technical documentation that sets the bar for quality, style, etc. What is the tone? 3. Workflow considerations: where does the information come from, how is it handled, where does it end up [Dragon Power Miro Board](https://miro.com/app/board/uXjVOsEycwA=/?share_link_id=77765985538) --- ### General Notes for a Non-Technical Writer - All repos require README files as MVdocs, to later be elaborated for DHdocs - Intro / elevator pitch - Quick start - Link to full documentation - Example implementation: try it out, getting started using a query - Learn more - Monorepo is the entry point to all the sub-repos. The monorepo README serves as an index/directory for the other repos. - *Should reference popular open source packages to observe how their READMEs are structured* - [MetaGame's monorepo](https://github.com/MetaFam/TheGame) - [FrontEndMasters Monorepo course](https://frontendmasters.com/courses/monorepos/) - [Nx monorepo](https://nx.dev/getting-started/intro) - Current DH docs are out of date. Might consider correlating to doc references. UX needs to be updated. - [npmjs](https://www.npmjs.com/): open source package manager for dev packages across the ecosystem --- ### Priotitization of Tasks - Review DH monorepo wiki: clean up doc architecture, use as a guide for future docs. - **Contracts:** *"Backend" Web3 devs.* Are important, but not even a DH product really. - **Subgraphs:** *"API layer" Web3 devs.* Are important, but currently poorly defined. - **Libraries:** *backend/dev ops, front end Web3 devs.* Are currently most important. - **SDK:** backend devs. Catch all for utilities, fetching, development kit. A library++: gives devs everything they need to interact with, build upon, etc., with data, querying, subgraph, contracts. - Gather examples of specific SDKs - Commons: helpers, constant variables throughout types, anything related to formatting - **DAOhaus Connect:** Actually finished, very useful. Lightweight, wraps quiver to return a Ceramic profile - **Feature/Component:** *front end devs* - **Apps:** *DAOs and DAO members, DH devs.* Being built in alpha version from the tools of the libraries. We are our own customers. - **Core UI:** *user facing.* will be structurally similar to v2. Docs will come later. - **Infra:** *backend/dev ops.* Decentralized tooling valuable to builders. A playbook to do exactly what we do *if* DH exploded today. - **Helm charts:** kinda like npm, a package manager for infra backend - **Kubernetes containers:** orchestrates cloud containers, like docker, opposed to monolithic servers - v2 is on AWS, but v3 is deployed on Digital Ocean - This is where our DH focus on decen really shines --- ### Inspiring Docs for Reference *Let's create a moodboard for different inspiring docs* - [React Docs Beta](https://beta.reactjs.org/) - [RainbowKit](https://www.rainbowkit.com/docs/introduction) - [Next.js](https://nextjs.org/docs) - [Cosmos SDK docs](https://docs.cosmos.network - [Algolia](https://www.algolia.com/doc/) - https://docusaurus.io/docs/search - https://docsearch.algolia.com/ - [Gnosis](https://docs.gnosis.io/protocol/) - [Lens](https://docs.lens.xyz/docs) - [Open Zeppelin](https://docs.openzeppelin.com/contracts/4.x/) - [ethereum foundation](https://ethereum.org/en/developers/docs/) - [Zora NFT Marketplace](https://docs.zora.co/) ##### Static Site Generators - [Nextra](https://nextra.vercel.app/) - [Docusaurus](https://docusaurus.io/) - https://docusaurus.io/showcase?tags=opensource - [Gitbook](https://www.gitbook.com/) ##### Readmes - [Gnosis SDK](https://github.com/safe-global/safe-apps-sdk/tree/master/packages/safe-apps-sdk) ##### Aux Resources - [Semantic Versioning](https://semver.org/) - [Awesome Contributing](https://github.com/mntnr/awesome-contributing) --- # Tuesday June 21, 2022 - We will start with reorganizing the DH monorepo Wiki, how it can be structured and navigated, make sure all the pages are accounted for. - Over the following weeks we want to focus on **adding READMEs and licenses to the individual repos** - We will collectively rethink the big buckets: create sub-categories for the existing groups - We will locate existing stray docs and put them into place - The wiki will serve as the SSOT for now. Info for individual repos will be distilled into READMEs. In the long-term, all of the wiki content will be migrated to a polish "dev docs" final deliverable. - Create a sticky note for each of the 76 (apprx) categories on the wiki - Top-down, standard hierarchy is appropriate - Labels are used for project management - Different audiences will be interested in different fidelities of info ### Checklist (in no particular order) - [x] Create a visual hierarchy of the components: sketch initial stratification of dev personnas - [x] Transfer wiki categories into Miro to arrange the visual hierarchy - [x] Collect examples of great docs from individual Magesmiths - [x] Create a README template for each package - [x] Create recurring meetings for README/docs jams - [ ] Sketch a checklist for how to submit/merge changes to the docs - READMEs for individual repos is highest priority - DH docs side: content of DH docs - How to make the pull request and submit PoW to DH - Software management best practices: versioning strategy, how are they announced, how do we communicate to the community about new releases - Contributor guidelines to encourage opens source --- ## Tuesday June 28, 2022 - [x] Organize the READMEs for each repo - [x] First pass at the structure of the READMEs - [x] Licensing and NPM/deployment (JP) - [x] Create [README Template](https://hackmd.io/GTnG2QmCQvyfLwROv7Sg6A) - [x] Create file of [daohaus-monorepo strucutre](https://hackmd.io/jB4zvXH2TEmzCJDNpbdt7Q?view) - [ ] Play with the IA of the Github Wiki - [ ] Revisit the dependencies of v3 diagram - [ ] Decide the "meta" structure of the docs in relation to the DH stack ### Action Items - [ ] Figure out the stack of the DH Docs (JP & Keating) --- ## June 30, 2022 - JP has been thrashed on the monorep and sub-repo READMEs - JP is working in `features-add-package-readmes` branch. Merge happens after all are complete. - Is Github the SSOT or HackMD? Answer: Github - What READMEs are still remaining? Answer: Helm, subgraph. JP has it covered. - Let's get clear on the phase of doc rollout (milestones) and decide where we're at. - Phase 1: ship MVP READMEs by Friday (90% complete) - Phase 2: format the Github IA/wiki - Phase 3: kick off on a more robust docs implementation - Phase 4: Final polished docs delivered by September 2 - QA for current MVP READMEs - Evaluate for inconsistencies (broken links) - Double check code syntax: make sure it's rendered as `code block` - Follow the instructions to make sure they work: UX testing - Standardize format across READMEs - proof editing ### Action Items - Write "blurbs" for each package: the *About* section in the upper right: high-level synopsis - V3 monorepo - Additional specific copy for different purposes for each package - TW (and others) can perform editing/QA --- ## June 12 - We will move forward with a stand alone docs site, ie: continuing on with the original plan. - Let's get clear about the MVP (this term is distracting): we are focusing on v1 of a documentation site. - CI/CD pub work flow: setup a repo specifically for docs - Create IA for the docs content: TW will spin up a HackMD Book - Design template: - monospace - serif - sans serif - color codes - possibly pulling from the V3 Figma? --- ## June 26 - Remove the mention of the monorepo, pivot towards the SDK - Setup a "starter": a few different packages that get a dev up and running - TW will write an intro to the Baal v3 #### TW will have 1:1 syncs this week: - Sam / Utilities, Data, and Subgraphs - Tues - Thoughts on docs IA - What subdomain for the docs? SDK-docs - Thoughts on naming? - Confirm subcategories - High-level of SDK: why have we done this, why is it important to the community - High-level overviews of each section - Keating / Ceramic, philosophy of the architectural decisions of DH infra (apps hosted on Skynet as a fully decen service, producer jobs on Digital Ocean and Kubernetes clusters) - TBD - If someone wanted to run their own Kubernetes cluster, is that possible and how would it be done? - Optional: Jord and/or Rowdy - UI + Features - Walkthrough Storybook - High-level design decisions, philosophy of the architecture - How we are approaching the component specs: modularity, composability, flexibility - How "legos" informs our features #### Changes: - Remove Code of Conduct and Community Links? - Replace Code of Conduct with a link to the DH Manifesto - Move Baal v3 down to Contracts/Infra, add a landing page/intro - Add to examples: set-by-step on how to get your app featured in our Docs - Articulate our philosophy of **open source tool kits**, no boundaries - Redraft the introduction to have a high-level overview of the SDK - conversational paragraph form: - what this is - why we did it this way - how to leverage it for your purposes - who to contact for a more personnal touch - so much can be built with these open source DAO principles - it amounts to so much more than the sum of its parts, more than just technical docs around APIs... *what can we empower each other to do with this?* - Add to Decen Infra: - Decen Infra intro (including Digital Ocean) - Why we have decided to host out infra on decen stack - Remove "Overview" section of UI (redundant) - Link Storybook into the UI section [https://storybook.daohaus.fun/] #### Tutorials - How to spin up ones own apps from a developer perspective - Just because we built it this way doesn't mean you (the dev) shouldn't try to build a better one. Then show us and we will feature your app in our docs! #### Practicalities - JP will setup repos and subdomains for both Baal and DHv3 docs - Need to decide on the semantic naming --- ## July 28 - TW will sync with Keating on Friday to capture content for these sections: - Ceramic Nodes - Helm Charts / Kubernetes - Jobs