# Contrib_X Docs WG -- Rolling shared meeting notes

_When a meeting is completed, the meeting notes are copied from here into a pull request for the repo [https://github.com/operate-first/community/tree/main/sig-community/wg-contrib_x-docs/meeting-notes](https://github.com/operate-first/community/tree/main/sig-community/wg-contrib_x-docs/meeting-notes) but you have to do the PR from your fork

We are holding this meeting under The OpenInfra Foundation Community Code of Conduct [https://openinfra.dev/legal/code-of-conduct/](https://openinfra.dev/legal/code-of-conduct/)

- [Code Of Conduct](https://openinfra.dev/legal/code-of-conduct)
- [Meeting Notes](https://hackmd.io/2QubjXl-T-65rnHaeYGGcg)
- [Project board](https://github.com/orgs/operate-first/projects/49)
- [Website Operate First](https://www.operate-first.cloud/)
- [Blog Operate First](https://www.operate-first.cloud/blog/)
- [Calendar Op1st Community Meetings](https://calendar.google.com/calendar/embed?src=operate.first.community%40gmail.com&ctz=America%2FNew_York)
---
## open for next meetings
- DevConf
- NERC - are there some topics for this WG?
- Design Reports
- Check docs path under each Contributor Role
- creating issues

## 2022-08-22
- Karsten Wade @quaid
- Thorsten Schwesig @schwesig

### Agenda and Notes:
- Name change of the group
- check and/ or change charter?
- As closing WG task, open up the discussion about forming "Docs SIG"
- Proposals:
- "Documentation WG"
- "New User Docs WG"
- "User and Contributor Docs WG"
- "~~User and Contributor Handbook WG~~" (too limiting, as READMEs etc. are location-based and not in a single handbook)
- "New User and Contributor Docs WG"
- "Community Cloud User Guide WG"
- Plain plan forward:
1. Rename to "Docs WG"
1. Announce to everyone we are adding to the scope so the group can exit into the Docs SIG
1. Meetings include time to talk about general docs topics
1. WG has two key focuses to finish:
1. Create or improve new user/contributor documentation
1. Draft the Docs SIG charter
- Finish and publish meeting notes

---
## 2022-08-08

### Attendees
- Karsten Wade @quaid
- Thorsten Schwesig @schwesig

### Agenda and Notes:
1. Momentum of this working group (follow up from last meeting)
1. July/ August as pto rich month
1. The meeting last week was accidentially cancelled
1. next time/ in general @schwesig will just jump in as the host
1. tools: mermaid in md, see chart below [cheat-sheet](https://jojozhuang.github.io/tutorial/mermaid-cheat-sheet/)
- https://mermaid-js.github.io/mermaid/#/./n00b-syntaxReference

### Actions
- [ ] check issues in the board

graph LR
A[Upstream Dev]
B[CI/CD]
C[Users]

    A --> B
    B --> C
    C -..-> A    

graph LR
A[Upstream Dev]
B[CI/CD]
C[Users]
D[Community Cloud]
E[Multiple Open Source projects, testing & proving]


    E -..-> D    
    A --> B
    B --> D
    D --> C
    C -..-> D
    C -..-> A

---
## 2022-07-25

### Attendees
- Karsten Wade @quaid
- Thorsten Schwesig @schwesig

### Agenda and Notes:
1. Agenda for the next weeks
1. new to github docs
1. We need a useful-for-all-occasions page for people who are new to GitHub, GitOps, and/or cloud native development.
- https://github.com/operate-first/community-handbook/issues/28
1. Walk-through of each persona on (getting started)[https://operate-first/getting-started] page, following each link and checking each page for usability and friendliness to new users/contributors.
1. https://www.operate-first.cloud/developer
1. In `Developer` section:
1. add diagram showing where and how operating-first changes/improves development [card](https://github.com/orgs/operate-first/projects/49#card-84496509)
1. link to template needs to go to [link](https://github.com/operate-first/support/issues/new?assignees=&labels=kind%2Fquestion&template=1_question.yaml&title=%3Cyour-issue-title%3E)
1. some explanation about this really open issues template [card](https://github.com/orgs/operate-first/projects/49#card-84496679)
1. canonical `GitOps definiton` [card](https://github.com/orgs/operate-first/projects/49#card-84496739)
1. Update `/developer` page `Learning Resources` section [card](https://github.com/orgs/operate-first/projects/49#card-84496926)
1. link to [Op1st community support](https://www.operate-first.cloud/community-handbook/support/README.md) is a 404, needs to be fixed to [?operate-first/support](https://github.com/operate-first/support
1. Remove link to old website at bottom - [card](https://github.com/orgs/operate-first/projects/49#card-84496848)
1. Update and expand "Learning Resources" section - [card](https://github.com/orgs/operate-first/projects/49#card-84496926)
1. remove source link from bottom of page [card](https://github.com/orgs/operate-first/projects/49#card-84496884)

### Actions
- Idea: in general: whenever we have a dead link about `support`, we should link to the [operate-first/support Repo](https://github.com/operate-first/support)

---
## 2022-07-18

### Attendees
- Karsten Wade @quaid
- Thorsten Schwesig @schwesig

### Agenda and Notes:
1. at the end of every meeting (during the meeting), the minutes will be merged via PR (approximately five minutes before the end):
1. tagging the people who participated
1. if sth needs to be corrected/added/updated, this can be done by a later PR
1. Describe the process first, find an automated solution later
1. If you do sth three times exactly the same, automate it
1. If you didn't do it at least three times exactly the same, don't automate it
1. `Curate and/or create-a-doc:` - a title for an issue where the CTA is to look for sufficient documentation to point at, then wrap it with whatever custom Operate First differences are relevant. E.g., how to make a PR can point to a chosen (curated) GitHub doc resource, then tell the differences or particulars for following those steps in the Op1st environment.

---
## 2022-07-11

### Attendees
- Karsten Wade @quaid
- Thorsten Schwesig @schwesig

### Agenda and Notes:
1. What tools can we reuse from the cloud native communities?
1`. https://mobile.twitter.com/kubectrl

## 2022-06-13

### Attendees
- Karsten Wade @quaid
- Cara Delia
- Thorsten Schwesig @schwesig

### Agenda and Notes:
1. What is our charter, when are we done?
1. Docs gap analysis vs.
1. Getting started path?
1. Is this page done?
1. Contributor ladder docs
1. Break down steps of making a contribution, is there documentation for each step?
1. Action: define the contribution ladder (technical, cultural)
1. NERC plan
1. User and Contributor Handbook
1. Landing page?

---

## 2022-05-09 Meeting

### Attendees:
- Stephanie Watson @stefwrite
- Sally O'Malley @sallyom

### Agenda and Notes:
1. Handbook updates status
1. We couldn't make any progress on this without other knowledge of the current status and what needs to be done next.
1. We need to get past the current open PRs before we can progress. **Who is in the position to get us past these PRs?**
1. Landing page for docs and training
1. We have two training courses that are published and ready to be part of a docs and training list.
1. We need to know where that list is going (a docs and training landing page). Maybe this needs to go back to the website WG?
1. **What other docs need to go into this list?**
1. Once we have a landing page, we should establish a list of TODOs and/or nice-to-have things.
1. From Sally: I'll dive in and add content and/or delegate to others to add content.

---

### Attendees:
- Karsten Wade @quaid
- Stephanie Watson @stefwrite
- Thorsten Schwesig @schwesig

### Agenda and Notes:
1. Looked at the open things needed in the community handbook repo:
1. List of PRs: https://github.com/operate-first/community-handbook/pulls
1. Naming it "User and Contributor Handbook" from a UI perspective, but leaving the repo as "community-handbook" for now.
1. Need to handle some of the PRs around converting the handbook to Jupyter Book before we can enhance it (the next things we want to do before Kubecon).

### Actions
- ...

---
## 2022-04-25 Meeting

### Attendees:
- Karsten Wade @quaid
- Stephanie Watson @stefwrite
- Sally O'Malley
- Cara Delia

### Agenda and Notes:
1. Karsten gave a review of everything we've been working on in this group so far and some relevant activities in the website group.
1. Errors in the PR process, such as `pre-commit` errors, are causing bumps in the proces of making PRs via the GitHub UI.
1. We can isolate and solve bumpiness for OS-Climate in two specific repos to start: `community-handbook` and `community`
1. User pathways:
1. Do we want to pre-filter by persona? At the start or eventually?
1. https://github.com/operate-first/community/issues/180
1. Or, how are you using the cloud? Running clusters, writing docs, running workloads, etc.

### Actions
- @quaid to announce handbook name change
- add what actions do people do to this issue https://github.com/operate-first/community/issues/180

---

## 2022-04-18 Meeting

### Attendees:
- Karsten Wade @quaid
- Stephanie Watson @stefwrite

### Agenda and Notes:
1. Karsten is working on recreating the Community Handbook in Jupyter Book
1. Need to think about if this is the right branding and structure; needs to be more specific about what's in there:
- "User and Contributor Guide"
- "User and Contributor Handbook"
- Description/tagline:
- "Guide for how to be a user and contributor."
- "Guide for how to participate as a user and contributor."
-
1. IDEA/PROPOSAL: Location of our work:
1. Website -- our work as a stand-alone Juypter page at: https://operate-first.cloud/getting-started(?)/
1. GitHub -- content maintained in the repo for the "Community Handbook"/"User and Contributor Handbook": `community-handbook/getting-started/README.md`
- `community-handbook/getting-started/MISC.md` -- Can contain files if needed, otherwise pulls in from docs in other repos.

## 2022-04-11 Watercooler notes

*Meeting cancelled due to lack of attendance & ability to record.
A watercooler discussion was held instead, notes below*

### People hanging out at this watercooler
- Cara
- Karsten

### Notes
- Action: setup DCO template for community handbook
- Project board: https://github.com/orgs/operate-first/projects/49

## 2022-04-04 Meeting

### Attendees:
- Karsten Wade @quaid
- Stephanie Watson @stefwrite
- Thorsten Schwesig @schwesig

### Agenda and Notes:
1. Working the new contrib pathway steps:
1. Easy to start: first 6 (more or less?) steps for "I would like to contribute to operate first community"
1. Understanding what an "Open Work" is
1. Clarifying what your contribution is, including what a contribution is in general.
1. Understanding the DCO (don't have a CLA) and how to write one
- Writing a commit message
1. Finding the appropriate repository for your contribution
- Description of each repository with link
- Note: each repository's README may have individual contributor guidelines
- **Reusable document**
1. Fork and branch the appropriate repository
- Cloning is optional
- For anyone _really_ new to GH, include a convenient list of actions to get started
- Link to a GH tutorial aligned with Op1st GitOps opinions
1. Joining the Operate First GitHub organization (have to be a member in order to contribute) - **this is the first PR one has to make**
- Making changes and creating a Pull Request
- **This is a generic reusable Op1st article**
1. Docs and training
1. How different in this community?
1. Training is intended to be a one-time use, once complete you don't return to it.
1. Documentation should be the baseline, single source of truth.
1. From an instructional design perspective, how are you keeping the trainee engaged?
1. "interactive vs flip book" where it comes to Jupyter Notebooks
1. If docs are written small and modular, then training is a path walk through the documentation

### Actions:
* ...

---

## 2022-03-28 Contrib_X Docs WG

### Attendees:
- Karsten Wade @quaid
- Cara Delia @cdeliaRH
- Sally O'Malley @sallyom
- Thorsten Schwesig @schwesig
- Amy Marrich @spotzz

### Agenda and Notes:

1. Focus
1. Help users in general
1. Engage users effectively
1. How to become comfortable to create a Pull Request (PR) at github
1. Easy to start: first 5 (more or less?) steps
1. I would like to contribute to operate first
1. What is "Open Work"?
1. What would you like to contribute?
1. Join the operate first organization (have to be a member in order to contribute)
1. DCO (don't have a CLA)
1. Find the appropriate repository for your contribution
1. link to description of each repository
1. note that each repository's README may have individual contributor guidelines
1. fork, clone, branch the appropriate repository
1. for anyone _really_ new to GH, a convenient list of actions to get started
1. link to a GH tutorial
1. make changes, create Pull Request
2. Where are we at and what do we need
1. Existing content - https://github.com/operate-first/community-handbook/issues/31
1. !Gap Analysis as mentioned last meeting
1. ?Next steps in team work, rather than alone
1. ?is this one of the next areas
1. https://github.com/operate-first/community/blob/main/program-management-tracker.md
1. Project board https://github.com/orgs/operate-first/projects/20
1. !START here today: https://github.com/operate-first/community-handbook/issues/28
1. collect links to docs we already have
1. focus: get on board, basi steps
1. are they still current/up to date
1. put together? better cross link
1. ?labels? are they used just in op1st or globally the same?

### Actions:
* ...

### Links
[Attachments 2022-03-28](https://hackmd.io/cSP8iYwqSIalHwAPx0A8fg)

---

## 2022-03-15 Kickoff planning

### Attendees:
- Cara Delia
- Stephanie Watson
- Karsten Wade

### Agenda:
- Organizing the WG
- Meeting time
- ACTION: Doodle poll based on next week for weekly call
- Announcing after this call
-
- Goal: Fill out first two rungs/layers of the contributor ladder
- Generic information everyone needs to know
- Much of it may exist, but we need to choose which ones to reference
- Create aggregate pages that give specific steps for how we do it in the project, and link out to where on e.g. GitHub is a full doc or tutorial on that.
- Handoff a reader to a persona-specific domain (if desired)
- Non-goals
- Persona domain specific content
- Defining GitOps best practices
- Gap analysis:
- What already exists out there
- ACTION: Create an issue for what exists
- What is needed
- ACTION: Create an issue for what is needed (brainstorm)
- Track Community Handbook board #20
- ACTION: Write up process to create doc-needed issues
- ACTION: write up how-to for this
- https://github.com/operate-first/community-handbook/issues
- Use issue templates for new things needed
- Use https://github.com/orgs/operate-first/projects/20 for tracking
- `area/contributor` and `kind/documentation`
- https://github.com/operate-first/community-handbook/issues/30
- https://github.com/operate-first/community-handbook/issues/31