As a [user, dev, plugin writer] I know which user facing features will be documented in core, and in the plugins
In Pulp 2, workflows were defined by pulp platform, and modified by plugins. This restricted the freedom of plugin writers substantially, but enforced somewhat similar workflows for all plugins. This architecture allowed many of the plugin features to be documented generally by pulp platform, with specific portions (importer, distributor configs) needing to be documented by each plugin.
With Pulp 3, plugins are given features by the plugin API that work out of the box for many situations. This makes it tempting to document these features in pulpcore to avoid repetition. As an example, consider the upload workflow. Pulpcore provides the API to upload artifacts, and the plugins use the plugin API to implement content unit creation. Neither feature is useful without the other. Pulpcore can say some general things about content unit creation, but must be overly vague to account for various plugin workflows. The resultant docs are not as helpful, and cannot be improved very much without stating incorrect information about some plugins.
The plugins have compensated for this somewhat by providing detailed quickstart guides for each of the features. Personally, I frequently use plugin docs, and rarely use pulpcore docs as a user.
This story is to add a section to the pulpcore docs entitled "How to use these docs".
This section will document for users, contributors, and plugin writers, what will be documented by pulpcore, and what will be documented by each plugin. All workflows will fall to the responsibility of each plugin. Pulpcore docs like artifact upload will remain in pulpcore in the reference guide. Plugin documentation will reference this to simplify their own "Upload workflow" documentation. The key shift is that the plugin documentation becomes the primary documentation for users.
Specific responsibilities (for user docs):¶
- High level explanations
- Install guide
- How to use these docs (including plugin docs)
- core provided REST API calls
- (suggestion to plugins) bullet list of Workflows
- sync (link to core for repository CRUD, repository version CRUD)
- publish (link to core for distribution CRUD, publication CD)
- upload (link to core for repository CRUD, artifact upload)
Specifically, this section should be renamed. https://docs.pulpproject.org/en/3.0/nightly/workflows/index.html
Nothing in here should be a complete workflow, instead, they will be generally useful components of plugin workflows. One idea for a name of this section is "General Core Features". Not a big fan, please suggest something better.
Clarify responsibility for core and plugin docs
The audiences for this patch are users and plugin writers, each needing to know how to approach the documentation since it is spread over multiple repositories. Users of Pulp 2 are especially in need of this, because the responsibility of documenting workflows have been moved to the plugin docs.
#4 Updated by email@example.com over 2 years ago
what about "Features provided by Core"
I like the idea of plugins responsibly documenting their workflows, especially if our target is to increase plugins number. Pulpcore docs will just not be able to keep track of everything and all the customizations, so documenting generic features in pulpcore and linking them in plugins makes sense to me.
Please register to edit this issue