# 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 - Topic: drop Pulp2 docs? - see https://discourse.pulpproject.org/t/pulp-2-docs/1101?u=ggainey - Topic: which new ordering mechanism should we use? - see https://github.com/pedro-psb/pulp-docs/issues/20 --- # 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.
Last changed by  
 
Pulp
Design/Discussion/Meeting minutes for https://pulpproject.org/
491

Read more

RPM meeting

discuss adopting zero-downtime-migration strategy

5/16/2024
Pulp/AH integration team meeting

Old link for the meeting notes https://hackmd.io/mrVY2804QnS1_xjQcx0p1gOld link for the pulp-container meeting notes* https://hackmd.io/z7i694VeTR-p4hgTk2Oocw

5/15/2024
Deployers Team Meeting

Triage Query:https://github.com/pulp/pulp-oci-images/issues?q=is%3Aissue+is%3Aopen+label%3ATriage-Neededhttps://github.com/pulp/pulp-operator/issues?q=is%3Aissue+is%3Aopen+label%3ATriage-Needed

5/14/2024
Pulpcore/katello/pulp_deb integration meeting

See also: https://discourse.pulpproject.org/t/katello-pulp-community-integration-meeting-minutes/39

5/14/2024
Read more from Pulp
Published on HackMD