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

[Robin Chan]

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