The Pulp community is beginning our drive to improve the user docs for Pulp 3.
Docs work is tracked with the redmine tags [Pulp 3, Documentation] and can be viewed from the query: https://pulp.plan.io/issues?query_id=128 <https://pulp.plan.io/issues?query_id=128>. (Note that the query is for "Documentation" OR "Pulp3", so shows more issues than we need to focus on here.) *Action Required:* Please have a look at the goals and the issues mentioned in "high priority work" section. If you have some extra time, please review some of the issues in the query or tag other issues you think should be included. There are a lot of issues, so it will take a focused effort from multiple people to tackle. *Work begun:* I've started by reading over our existing documentation for pulpcore. This etherpad was used for organizing and compiling issues. [0] https://docs.pulpproject.org/en/3.0/nightly/ *Docs Push Goals*: - Address OSAS Feedback https://pulpproject.org/2018/09/17/pulp-community-health-audit/ - Add quickstarts - make pups visible on pulpproject.org - community visible calendar - Collaborative effort coordinated via Redmine - File issues for documentation gaps - Close irrelevant/dupes/already-done issues - Burn down *High Priority Work:* >From the review below, 2 important changes should be addressed early in the docs push. These issues would benefit from feedback, please review and comment! - Explicitly define which features will be documented by pulpcore, and which will be documented by each plugin - https://pulp.plan.io/issues/4626 - The division criteria (discussed on the issue) needs to be more concrete - Publish better REST API documentation for pulpcore - Publish the live-api docs (many options): https://pulp.plan.io/issues/4636 - Document how to ^ for plugin writers: https://pulp.plan.io/issues/4637 *State of the docs, and what can be improved:* The docs appear to be in pretty good shape, but have some work left to do. The content of the current docs is mostly strong and concise [biased by familiarity]. The organization is fine, though some clean-up would improve readability, and clarity of the left-bar main divisions. Isolated problems are mentioned in the read-through notes on the planning etherpad. [0] The division of the docs (between pulpcore and each plugin) requires prior knowledge and is not well communicated. Based on the consistency, the developers have a shared understanding of which features should be documented in pulpcore, and which topics are owned by the plugin. In my opinion, most of the documentation on pulpcore is in the right place. The Plugin docs are off to a good start by covering each major feature with quickstart-style guides. Pulcore and each plugin's docs need to include more specific information, which should be covered by the REST API docs. REST API documentation is published on pulpcore's read the docs, but it is missing too much information, rendering it practically useless. https://docs.pulpproject.org/en/3.0/nightly/integration-guide/rest-api/index.html#pulpcore-rest-api . Significantly better REST API docs can be viewed at the docs endpoint on a live-running pulp instance. The live REST API documentation partially fills the gap between the quickstart docs (major feature) and how that workflow can be altered (minor features). Unfortunately, these docs are not published, they are only available if the user takes the extra step of generating the documentation. *Plan:* 1. Begin by improving the REST API docs-- their inclusion will add a lot of "missing" information. This will affect a lot of the following docs work, allowing plugin writers to link to specific API calls, reducing the need and length for text explanations. 2. Clarify any discrepancy about what is expected to be documented by each plugin. This needs to be very clear to users, qe, and anyone who contributes docs, especially plugin writers. Necessary for successful documentation navigation. 3. Understand, revise, and groom issues from the docs planning backlog [0] https://etherpad.net/p/Pulp3_Docs_Planning
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev
