Hi Austin, Thank you for pulling this all together and sharing it out. 2 thoughts: 1. What is the difference btween ln 34 & 127 of the [0] etherpad? Looks like a repeat to me. 2. I'd like to hear more about this idea of not being able to distinguish if a feature is documented in pulpcore or a plugin. Who is the audience for this document? If it is the user, I would dig a little deeper question as assumption that a user should have to know where it's documented. I would think if I really do need to know, then I'm looking for different, more general, high level information about the feature. If I'm a user of a specific plugin then I'm looking for how this feature works for a specific plugin and so therefore we might be able to re-use details - but what if this plugin decided not to use this feature or customized it somehow. Granted I think we need to make this super easy to document if a plugin is using a feature in a straightforward way but do we need to make it customizable or have additional info specific to a plugin? In order to not make suggest a large change, I'd say, why not allow users to find the feature details within the plugin docs?
-Robin On Wed, Apr 3, 2019 at 1:32 PM Austin Macdonald <aus...@redhat.com> wrote: > 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 >
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev
