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
/docsfolder 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
- Which build technology to use (mkdocs, mymst, docusaurus, sphinx-md, …)
- …
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:
-
Two docs (temporarily):
Create new/docs, restructure content from scratch and keep old docs until done -
One docs:
Migrate all old docs to markdown, then restructure content in-place
We’ve chosen the first because:
- the alternative is costly (there are a lot of subtitles when converting rst->md).
- moving (copying/pasting) to a fresh structure should be easier than in-place re-structuring
- 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.