"Unified Docs" Plan

Hello everyone,

The Documentation Workgroup has discussed some strategies for starting out our efforts, and I’ll summarize here our first draft of the plan. In the end, there is a Justification section outlining why we came to this set of decisions.

Please share any thought on this and let’s make those docs great.

The Plan: Part 1

Goal

  • Have one documentation site for all content.

Non-goals

  • Immediately improve quality of existing content. The focus is to have the functional single site experience.
  • Generally, other doc-related improvements that are nice-to-have but could be done later.

Core

Some core decision about how to approach it.

  • Architecture: Each plugin specific-docs lives in the plugin repository and is aggregated on build-time
  • File format: Markdown
  • Versioning: In-place identifiers for version-specific content. The main docs won’t be versioned
  • Content Organization: Content should have logical and intuitive categories

Plan

Next steps towards reaching the goal.

  • [workgroup] Initial Infrastructure: Setup the new main-docs website
    • register domains and setup build system
    • new GH runner that aggregates from repos and publishes to a new domain
  • [workgroup] Content Framework: Write a practical “Doc Contribution” guide
    • based on Diataxis, define pulp content types, writing styles, templates, etc
    • provide decision-tree like guidance.
  • [common] Create new /docs folder inside each plugin-repo:
    • Use previous guide to standardize basic structure/content types across repos
    • Transpose content from old docs to the new ones
    • All new doc activity will focus on new-docs. Old documentation as is kept as is until process is done.

Open Questions


Justification

Summary of the discussion about each topic which lead us to this plan.

Architecture

The alternative is monorepo, but we’ve all agreed that having docs apart from code would be impractical for us.

File format

This also seems a consensus that markdown is a popular and practical choice.

We’ve initially decided not to worry too much on which build technology to use (mkdocs, MyMst, or other), as the general effort of this task-force (one-docs) can be accomplished mostly with “agnostic” markdown files.

Versioning

Ideally, we’ll have this one site where each repository-specific page had its proper version-toggle, but that’s more than we can do in a timely manner.

In-place identifiers to mark version specific content (such as introduced in and legacy) seems a good balance between feasibility and user experience. These curated marks should cover relevant historic information for most users, and for edge cases one can always look into the branch history, which should renders reasonably out-of-the-box.

As further alternatives to improve this experience, we could setup individual builds for each repo, as to generate “plugin archive documentations”, which could easily be versioned.

Content organization

The plugin architecture makes content organization complex.

To address this more systematically, we’ve chosen to adopt Diataxis as the basis of content organization and derive a guide tailored for Pulp needs. This guide should provide a dead-simple decision tree about what a content is, for who it is targeted, and then prescribe where it goes and how it’s written (template).

Without such an artifact, it would be very hard to aggregate various sources in a single site in a way that feels consistent.

Migration Step

This is about the step “Create new /docs folder inside each plugin-repo”.

We’ve discussed mainly two approaches:

  1. Two docs (temporarily):
    Create new /docs, restructure content from scratch and keep old docs until done
  2. One docs:
    Migrate all old docs to markdown, then restructure content in-place

We’ve chosen the first because:

  1. the alternative is costly (there are a lot of subtitles when converting rst->md).
  2. moving (copying/pasting) to a fresh structure should be easier than in-place re-structuring
  3. faster reaching the goal of having a unified website up and running

There are some drawbacks, the main one being that during this transition phase it will be confusing to have two docs when some change needs to be made (on everyday work). A general policy of “focus on new” should ease that, and we can think in other ways to make that work better.

3 Likes

The working group met earlier today. Our latest accomplishments include:

  • Pedro created a pulp-docs[0] CLI that has commands for building and serving the new docs site.
  • A GitHub Actions workflow[1] has been created to publish docs built using pulp-docs to https://staging-docs.pulpproject.org/.

We will soon be ready to start organizing the new documentation according to the plan outlined here[2]. We ask everyone who is interested in how the new documentation will be organized to review this plan and the demo site.

[0] GitHub - pedro-psb/pulp-docs: Python Package to help aggregating Pulp's multirepo ecosystem into a unified doc.
[1] Publish staging-docs.pulpproject.org · Workflow runs · pulp/pulpcore · GitHub
[2] https://hackmd.io/@pbrochad/SyfGeQc86

3 Likes

Summary - 12/01/2024

Today we’ve discussed and defined:

  • Content Migration Workflow: first steps to start migrating to new docs
  • Markdown Style Guide:
    • basic standard: links, code and other syntax examples
    • not using include feature (repos that use should migrate)
    • not keeping curl examples (pulp-cli)

Get involved:

  • The purpose of above definitions is to make migration easy and consistent. Please, review these here and share your thoughts.
  • Feel free to review other parts of the document aswell and reach out to us.

Group directions:

  • Until now, we have achieved a set of working tools, infrastructure, and conceptualization.
  • From now on, we should experiment and fine-tune the migration experience:
    1. start/experiment with the process with a small set of repositories
    2. fix/adjust any critical problem with tooling, workflow, structure and what-else
    3. share/collaborate with other mini-teams in rounds until finished

Full notes here: Docs Working Group - HackMD

1 Like

We met again today. We are continuing to experiment with documentation structure. Our latest experiment will be to structure the top navigation by persona so it will look like this:

Home | Getting Started | Usage | Administration | Reference | Development | Help

What do you think about such category names? Is there a different way you wish to structure the top navigation?

2 Likes

Docs Office Hours Week #1

This week we started doing Docs Office Hours to work on the docs migration.
We plan to carry these over until the end of March 2024.

Here’s a summary of this week progress:

  • pulp_python: done by Gerrod
  • pulp_rpm: in progress by Grant
  • pulp_operator: Humberto and Ina learned in the meeting, will do later

Notes:

  • Some doubt about “Guide” vs “Tutorial” content
  • “Reference” content still doesnt show up in the preview

Helpful links:

Docs Office Hours Week #2

Here’s a summary of this week progress:

  • pulp_rpm: Grant finished in about total 5h, which included categorizing content and improving the style (adding tabbed content, etc).
  • pulp_operator: Ina finished in about 4h

Notes:

  • pulp-docs needs to catch-up on supporting nested packages
  • small bugfix in pulp-docs

Helpful links: "Unified Docs" Plan - #5 by pedro-psb

Here’s a summary of this week progress:

  • pulp_certguard + pulp_file: PRs opened by Grant
  • pulp_ostree: Finished by Lubos (in no more than 1h)
  • pulp_container: PR opened by Lubos (in about 4h)
  • pulp_ansible: Gerrod will take it
  • pulpcore-selinux: PR opened by Pedro (less than 1h)

Notes:

  • pulp-docs added support for nested packages and plugin overviews (staging_docs/{persona}/index.md)
  • Website was rounded-up: reference and help sections “resolved”
  • Google Analytics added by Dennis

Helpful links: “Unified Docs” Plan - #5 by pedro-psb

2 Likes