Thank you for writing up this email. I reviewed high priority tickets and left some comments.
-------- Regards, Ina Panova Software Engineer| Pulp| Red Hat Inc. "Do not go where the path may lead, go instead where there is no path and leave a trail." On Thu, Apr 4, 2019 at 10:54 PM Kersom <ker...@redhat.com> wrote: > Hi Austin, > > Thanks for working on this. > > 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. >> > > This division can be very helpful to assure that we are writing tests for > features in proper places - avoiding regression in the right pulp component. > > Right now we are testing: > > 1. pulpcore features > 2. pulpcore features that require a plugin in order to be tested. We are > currently using the pulp_file [0] to test those pulpcore features > 3. plugin features > > Since tests live in different repos, we do our best to put the tests in > the proper repository. > > But pulp_file does not exercise all features from pulpcore. What are the > other feautres form pulpcore that we are not testing that require a > different plugin? > > The suggested documentaiton division will help find those gaps, and for > users later on, it will help to know how to report a bug with the right > component. > > > https://github.com/pulp/pulpcore/tree/master/pulpcore/tests/functional/api/using_plugin > > > On Thu, Apr 4, 2019 at 12:26 PM Robin Chan <rc...@redhat.com> wrote: > >> 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 >> > _______________________________________________ > 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
