[Pulp-dev] State of the docs & Docs drive kickoff

Ina Panova ipanova at redhat.com
Mon Apr 15 11:06:51 UTC 2019


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 <kersom at 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 <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 [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 <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 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 at redhat.com
>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>> _______________________________________________
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20190415/174d67af/attachment.htm>


More information about the Pulp-dev mailing list