---
# System prepended metadata

title: 'Magesmiths v3 Documentation: JP+E2T+TW Sync'
tags: [gutenberg-galaxy]

---

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