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

[Austin Macdonald]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20190403/6fb285b4/attachment.htm>