# Bookmarks

- [Brainstorm Roadmap](https://hackmd.io/@pbrochad/SyisQfcUp): A place to put docs ideas for the future.
- [Pulp Unified Docs 1: The great migration](https://hackmd.io/@pbrochad/SyfGeQc86) - (see also the [Migration Epic](https://github.com/pulp/pulpcore/issues/5037))
- [Pulp Unified Docs 2: Tidying things up](https://hackmd.io/OORLGS8QT9ir6KnteSuYnw)

---

# Agenda

---
# June 05, 2024

- state of things:
- most "essential" stuff done
- https://github.com/pulp/pulp-docs/issues/30
- changelog, odering-mechanism/link-stabiltiy, PRs CI, and misc improvements
- rest api docs:
- mkdocs plugin for swagger-ui works but anchor linking doesnt work. Thats bad
- tried finding javascript redhatter for fix that (slack), but no success
- alternative: try at least unifying the rest api in only one "external page"
- https://redocly.com/blog/api-discovery/#sidebar-navigation
- "must-have" remaining is **publish the docs** and **deactivate-redirect old docs**
- we can see what "nice-to-have" we should prioritize this month
- discussions:
- publish to pulproject.org process
- talk to infra people
- redirect old docs
- keep pulp2
- keep versioned docs if its easy enough
- dont delete old files from the webserver, archive them somewhere public
- content improvement is tomorrows problem, we are good for now
- possibly close the working group and celebrate our accomplishments so a new one can be formed with a new problem statement
- AI:
- create discourse post to ask people what pages (urls) from pulproject.org they think are valuable
- get and archive old docs on a repository
- ask infra people to change publishing in 2/3 weeks and do redirects
- review remaining CI update (changelog) PRs:
- https://github.com/pulp/pulp_maven/pulls
- https://github.com/pulp/pulp_container/pulls
- https://github.com/pulp/pulp_ostree/pulls

# March 13, 2024

- Topic: Entirely replace pulpproject.org website? Yes
- Draft Q1 plan:

Q1
Increase the adoption of Pulp upstream by improving the documentation for new and existing users.
- Create a unified documentation site
- Make contributing to the documentation easier
- Systematically structure the documentation content

Q2 - Proposal
Increase the adoption of Pulp upstream by improving the documentation for new and existing users.
- Make the staging-docs stable and production ready
- Content improvement and de-duplication
- Setup doc-CI and improve current publish workflow

Detailed Q2 discussions:
- Make the staging-docs stable and production ready
- integrate changelog links
- See https://staging-docs.pulpproject.org/pulp-docs/docs/sections/user/
- changelog needs to be generated to .md not .rst
- integrate REST API links
- See https://staging-docs.pulpproject.org/pulp-docs/docs/sections/user/
- maybe add pointer at the top of each plugin section?
- version needs to be filled in
- fix ordering mechanism problem (no renaming files)
- move pulp-docs to pulp organization
- Content improvement and de-duplication
- fill in the "voids" in our pulpcore staging-docs (eg, "Getting Started")
- start migrating content from pulpproject.org into the staging-docs hierarchy
- poss use this content to fill the holes above
- Ultimately - replace current pulpproject.org with the output of staging-docs efforts
- Add base CI and automation infrastructure for auto-build/test/publish of new-docs-location
- doc-only changes should run *only* docs-CI (ie, not full code test suites)
- setup the docs-CI (e.g, test builds)
- pipeline needs to account for "plugin Foo releases, docs-site rebuilds"

# February 02, 2024

Agenda
- Review the work from the last 2 weeks
- Plan the "Intro Tutorial"
- Topic: Move `pulp-docs` to pulp organization?

Notes
- let's start defining a style-guide (ie, workflow-titles are "VERB a NOUN" format)
- ggainey doing initial work/experimentation on pulp_rpm
- dkliban would like "someone else" to get familiar with the pulpdocs tooling and start picking up some support
- ggainey tentative "yes", pending flattening current COPR/Satellite work
- proposal:
- ggainey/dkliban/pbrochado meet next week to get ggainey up to speed
- record and post to youtube
- write up a detailed "how to" to discourse
- host "office hours" of docs-team, to help plugin teams get moving
- in discourse/team-mtg, announce "ready for plugins to start the work"
- announce short twice-wk "office hours" (30 min?)
- one observation: convert the content **as is** and merge
- DO NOT UPDATE THE DOCS, until after the conversion is DONE
- once tmp_docs is EMPTY AND MERGED, **then** you can start editing to correct content
- second observation: diagrams
- what's a better way to handle them?
- mermaid?
- use web-service?
- THINK about this - but let's not DO any thing about it, until CONVERSIONS ARE DONE
- demo: "edit button" takes you (or will take you) directly to the markdown-doc that you want to change, and will open a PR against the right place!!
- discussion RE current TOC
- "Getting Started" - for core, we need an overview page?
- is "Overview" the overture? or is it the ad/preview of the concert?
- it should be "How to use this documentation"
- "tutorial"'s goal, is "do these steps, and at the end, you will have a working repository"

Action Items
- dkliban to set up ofc-hours sched for Q1
- pedro move pulp-docs to pulp org

# January 19, 2024

Agenda

- Last week feedback
- Content-Type design: should we separate content between Admin/User? Some thoughts
1. will it be confusing for a contributor to decide between Admin and User? No
2. is it correct to assume that:
- *Plugins* are usually targeted at *User*? No, they have admin content too
- *Others* are usually targeted at *Admins*? Probably, but not necessarily
- Frontpage:
- It shouldn't be too busy and present the most relevant paths/links
- It's good that we don't have to scroll too much
- New Top navigation experiment:
Home | Getting Started | Usage | Administration | Reference | Development | Help

Action Items:

- [dennis+pedro] Work on pulp-gem togheter
- [dennis+pedro] Work on pulpcore (common material) togheter
- [pedro] re-structure main navigation

# January 12, 2024

Agenda

- **Initial feature definitions**: we should define standard ways of doing some fundamental things within markdown, so we avoid re-work in the future. I've started defining those [here](https://hackmd.io/eE3kG8qhT9eohRYbtooNww?both#Markdown-specifics). Some needs some special discussion:
- *absolute vs relative* links
- *file includes*
- *tabs for http/cli methods*
- Notes
- style-guide enforcement should be enforced/enforceable by CI/scripting
- WG prefers custom-absolute-links vs relative-links
- WG prefers no-include-files
- makes things MUCH easier for contributors
- how to write examples
- CLI/API/bindings are all possibilities
- API examples are confusing/hard-to-write
- "just use pulp-cli -vvv to see examples"
- if there's a gap in the CLI - let's use a bindings-example? instead of API?
- OR - if there's a gap - we don't have an example, until there is CLI coverage
- just link to REST API and have discussion
- CONCLUSION: use CLI (only) for examples, point to REST API for anything not covered
- pulp-docs update
- basic functionality is working
- time for more people to start playing with it!
- currently only works for pulpcore
- "where is this group going?"
- have one example of how a non-core repo now looks
- then farm out to the mini-team repos, with a proposed deadline
- first non-core repo should be "small", but "high-value"
- pulp-oci-images?
- also want a plugin repo
- pulp-gem? pulp-maven?

Action Items

- ggainey|dkliban: use pulp-docs
- dkliban: prepare pulp-oci-images as the pulp-docs example repo
- pedro:
- post style-guide link on discourse (style guide and migration workflow)
- make sure plugins/extensions in style docs work

# January 05, 2024

Topics

- [all] review design docs (and share)
- [pedro] briefly present `pulp-docs`
- Goals for docs building
- requires no setup
- let devs with existing checkouts have their checkouts be used
- lets non-devs easily contribute
- runs linting on all the docs being built
- ideas for improving pulp-docs
- instead of cloning everything to /tmp, check if ../ for the repository and only clone to /tmp if it's not there. Use existing repos when building the docs.
- if all repos are cloned to /tmp emit a message saying that a read only version of the repositories is being used
- if the branch in the existing repository does not match the configuration file, a message about this inconsistency should be emitted. inconsistent being either mismatching branch or mismatching REF

# December 15, 2023

- [pedro] put together a demo of top and left navigation
- https://pedro-psb.github.io/the-docs-demo/
- questions
- can diff repo provide sections to be included (eg into "Fundamentals")? - yes
- do the repos have any way to decide order?
- would be good to be able to "auto-fetch" from repos based on "known locations"
- need a dir-tree of these known-locations
- what content-type should be used in Quickstart?
- pulp_file?
- we can point to fixtures
- BUT - doesn't give end-to-end (ie consumption by a client)
- use "highest use/value" - ie, pulp_rpm?
- OR - plugin we'd like to see most growth in?
- let's use pulp_rpm
- and go all the way through to "dnf install foo"
- User Guides
- provide templates for these
- do we need pulpcore guides?
- two personas, "Pulp Instance Admin" and "Pulp User"
- User Guide should be for the latter, only
- "I just want to create sync and publish repositorioes"
- Admin Guide section
- "I need to get this instance configured and keep it running"
- Maybe Guides\UserGuides\(per-content-type),AdminGuides\blahblahblah
- bring REST API "inside" these docs?
- might want to use a diff docs-gen-tool?
- let's experiment
- "plugins aren't 'real' unless you're in the all-in-one" - generate All The Docs from all-in-one?
- REST useability issue with "{foo-href}" in current REST docs
- there is a fix for this
- can we get this into the plugin template, like, "next week"
- Can we have "edit me" buttons, on the doc site, to make it Really Easy to submit docs-PRs
- GOAL: make doc-contribution as easy as humanly possible
- GOAL: one can set up documentation hub **without** needing a fully-running dev-env
- DO NOT need a live-server just for "building the docs site"
- Reducing friction: introduce githook to lint at PR-time?
- can we bug ddavis' initial experimentation?
- REMINDER: let's stay at the Big Picture/Organizational Level
- once we have Something, we can start on continual improvement
- REMINDER: this group's goal, is to lower the friction OF DOC CONTRIBUTION
- there's a larger issue, to lower contribution-friction generally
- but for THIS WG, stay focused
- One "Contribution" section - yes please
- do we separate "Docs Contributing" and "Developer Guide/Contribution"?
- GOAL: structure around Personas
- User
- Admin
- Developer
- can we get an order-of-implementation publicized
- want to start getting buy-in from the mini-teams
- section-templates
- https://hackmd.io/V7vHsqM6S0-Het87CjaOAw

Action items:
- [dkliban + bmbouter] update the issue https://github.com/pulp/pulpcore/issues/4850
- [pedro] explore mkdocs multirepo prototyping

# December 8, 2023

- we should include docs on how to generate your own bindings
- mkdocs or docusaurus?
- We will start with mkdocs
- How do we bring all the documentation together?
- https://github.com/jdoiro3/mkdocs-multirepo-plugin
- This group needs to come up with a a guide for contributing the docs.
- We should put together a list of all 'deliverables'.
- Contribution
- Installation

- content repos
* pulp_rpm
* pulp_ansible
* pulp_maven
* pulp_certguard
* pulp_deb
* pulp_python
* pulp_ostree
* pulp_npm
* pulp_gem
* pulp_container
* pulp_file
- other repos
* pulpcore
* pulp-operator
* oci-env
* pulp-cli
* k8s-resources
* squeezer
* pulp-openapi-generator
* pulp-oci-images
* pulpcore-selinux

Actions items:
- [dkliban + bmbouter] update the issue https://github.com/pulp/pulpcore/issues/4850
- [pedro] put together a demo of top and left navigation

# December 1, 2023

## Action items
* ~~- [dkliban] get new website set up~~
* ~~- [pedro] post the goals and plan on discourse along with a write up "why are we doing it this way?"~~
* ~~[decko] A way to build markdown from rst https://github.com/pulp/pulp_maven/pull/182~~

## Some questions

- What documentation format do we want to use?
- Markdown (switching from ReStructured Text)

- docs goals
- have everything including general, plugin, developer docs all in one place (organized but one site)
- no longer versioning the site
- add "introduced in" and "legacy" identifiers

- the plan
- the existing documentation sites will be left 100% as is
- same builder, same RST, same domain name sites, etc
- a new docs site created
- built with a new GH runner that publishes to a new domain, that knows how to pull from multiple repos
- write a how-docs-are-organized doc
- each repo with have a new directory created to contain the new markdown docs, organized according to "how organized" doc
- populate new-docs w/ MD conversion/rewrite of existing docs
- all new docs activity (from the working group) will focus on the new site
- not going to have a "versioned" doc-site
- have a static docs-gen per-repo for each version/release?
- it's .md, and lives in the individual repos - just go to the branch and read it

-----

- reasoning
-

- how do we get there?
- focus areas
- onboarding experience/day-0/install-setup needs Work
- "best practices" workflows
- pulp-administration workflows (e.g., backup/restore)
- framework for effective contributor-contribution
- task-oriented guide for "how to write pulp docs"
- https://diataxis.fr/needs/#characteristics-of-documentation
- https://mystmd.org/
- https://pypi.org/project/sphinx-markdown-builder/

- Where each plugin documentation should live?
- monorepo docs - more hard for each team to maintain, easier to build
- multi-repo docs - more easy for each team to maintain, more hard to build

- How to handle multiple versions for each plugin? (single site docs)
- use “introduced in v1.2.3” and legacy section for relevant stuff
- two builds:
- aggregation build on the main doc-site (build/versioned on pulp-core releases, because it’s frequent)
- stand-alone for archiving purposes (like published with github pages for each plugin, most reliable if someone is looking for a specific old-release thing).
- How can the migration happen?
- gradual-migration:
- each plugin migrates to a stand-alone version (complying with the unified doc stack)
- pulpcore (assuming it hosts the main “doc”) migrates last with the aggregation step.
- instant-migration
- each plugin creates an alternative offline doc version but keeps the old one running
- synced up deprecation of old docs and activation of new
- How to handle redirect from old pages?
…
- What doc building technology should we use?
- mkdocs - good plugin ecosystem and uses markdown (used in CLI, operator)
- static content to upload
- does this support templates/boilerplates to be reused in plugins?
- docusaurus (md/js) - really like UI, uses markdown but JS
- uses React
- overkill "for now"
- sphinx - rst (used everywhere else)
- Used to be the standard in Python world
- https://pypi.org/project/sphinx-markdown-builder/
…
- [decko] Should we have a diagnosys of the actual state of the documentation?
- Obeys a standart?
- Exposes what is the Pulp project?
- Have API usage examples?
- ...

- notes
- ggainey : what is the focus for this specific docs-effort?
- pedro: prepped a presentation
- [Discourse thread](https://discourse.pulpproject.org/t/pulp-documentation-working-group-forming/1040/3)
- let's be explicit: implied goal of this group is "move to markdown"
- build technology is a second discussion/goal
- reduce the number of clicks a user needs to make, to get from (say) a container-registry page to "pulp is installed"
- this is prob a "later" goal - let's get our pulpproj.org house in order first
- maybe `pandoc` to automatically convert rst to md.
- a gh action would be amazing
- sphinx to build rst and md at the same time
- https://pypi.org/project/sphinx-markdown-builder/

# November 17, 2023

- dkliban will setup newdocs.pulpproject.org and have pulpcore repository start publishing there.