[Pulp-dev] State of the docs & Docs drive kickoff
kersom at redhat.com
Thu Apr 4 20:53:41 UTC 2019
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  to test those pulpcore features
3. plugin features
Since tests live in different repos, we do our best to put the tests in the
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
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
On Thu, Apr 4, 2019 at 12:26 PM Robin Chan <rchan at 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  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?
> On Wed, Apr 3, 2019 at 1:32 PM Austin Macdonald <austin at 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
>> *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. 
>> *Docs Push Goals*:
>> - Address OSAS Feedback
>> - 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
>> - 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
>> - Publish better REST API documentation for pulpcore
>> - Publish the live-api docs (many options):
>> - Document how to ^ for plugin writers:
>> *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. 
>> 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.
>> . 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.
>> 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
>>  https://etherpad.net/p/Pulp3_Docs_Planning
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
> Pulp-dev mailing list
> Pulp-dev at redhat.com
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Pulp-dev