owned this note   changed 10 months ago  
Published Linked with GitHub

Bookmarks

Agenda

June 05, 2024

  • state of things:
    • most "essential" stuff done
    • rest api docs:
    • "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:

March 13, 2024

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
  • 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. 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

Action items:

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?

  • 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:

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?

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

November 17, 2023

Select a repo