Improving our overall docs experience

We have had feedback from many channels that the overall entry points to using Pulp are not easy. Our docs don’t help this.

I think that there has been every effort to make the docs work in their current format. However diligent project contributors are in adding documentation as part of each new feature, we seem to have problems on a structural basis that keep hampering user progress through Pulp.

If anyone is interested in working with me on putting together a plan and making Pulp docs better, please let me know. More than likely, we will start meeting and working on this in the new year.

If anyone has particularly frustrating feedback that they want to share about trying to use Pulp docs, also feel free to share here. The more we know about, the more we can fix.

TL;DR I want to create a docs working group. Do you want to join?

3 Likes

I’d like to participate in this. Feel free to send me an invite for any working hour that is free. Thanks for organizing this!

1 Like

I’d like to join as well.

1 Like

I want to join

2 Likes

Just wanted to mention pulp-cli help strings as a topic to think about as part of the “overall docs experience”. Pulp CLI can provide a very good entry point for new users to understand Pulp. However, help strings are currently quite limited.

We should put some careful thought into how such help strings can be made to be consistent across plugins. Adding good examples to the common commands and options shared across all plugins would be one way to start. I can also see certain phrases (e.g.: “; can be specified multiple times.”) being used again and again. Should such phrases be defined in just one place and reused everywhere, or would that over-complicate things?

Another question might be whether part of the API docs could possibly somehow be reused for the pulp-cli help?

@x9c4 Any thoughts? Am I missing something in my understanding of the current state of pulp-cli help strings?

3 Likes

@x9c4 - is there any way you could generate a list of all the CLI command help for me? I would be happy to take a look and see if I can make suggestions. I can raise a PR then.

2 Likes

I might eat my words but at the moment, I am over halfway through reading every line of command help in the CLI. Its uniformity surprised me. I am unsure if I will have anything substantial to contribute to this.

At the same time, I am not working with it. That is probably a whole other experience. For the most part I had this same sensation when I started to look at Pulp for the first time. It took a while for me to see the potential issues with our docset.

@quba42 can you give me an example of where you think an example would help the user?

@mcorr Well with respect to CLI, a lot of options simply don’t have any help string/description. See for example:

(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp deb remote --help
Usage: pulp deb remote [OPTIONS] COMMAND [ARGS]...

Options:
  -t, --type [apt]
  --help            Show this message and exit.

Commands:
  create
  destroy
  label
  list
  show
  update
(pulp) [vagrant@pulp3-source-fedora35 ~]$ pulp deb remote create --help
Usage: pulp deb remote create [OPTIONS]

  Create a apt remote.

Options:
  --name TEXT                     [required]
  --url TEXT                      [required]
  --ca-cert TEXT                  a PEM encoded CA certificate or @file
                                  containing same
  --client-cert TEXT              a PEM encoded client certificate or @file
                                  containing same
  --client-key TEXT               a PEM encode private key or @file containing
                                  same
  --connect-timeout FLOAT
  --download-concurrency INTEGER  total number of simultaneous connections
  --password TEXT
  --proxy-url TEXT
  --proxy-username TEXT
  --proxy-password TEXT
  --rate-limit INTEGER            limit download rate in requests per second
  --sock-connect-timeout FLOAT
  --sock-read-timeout FLOAT
  --tls-validation BOOLEAN
  --total-timeout FLOAT
  --username TEXT
  --policy [immediate|on_demand|streamed]
  --component TEXT                Component to sync; can be specified multiple
                                  times. Will sync all available if specified
                                  once with the empty string.
  --architecture TEXT             Architecture to sync; can be specified
                                  multiple times. Will sync all available if
                                  specified once with the empty string.
  --distribution TEXT             Distribution to sync; can be specified
                                  multiple times.  [required]
  --help                          Show this message and exit.

[required] is added automatically for any required options by the framework. However, beyond this --name, --url, --connect-timeout, --password, and many others don’t have any help strings/descriptions.
I added help strings for the debian specific options --component, --architecture, --distribution, including the phrase “; can be specified multiple times.” which I copied from the rpm cli help. But unlike [required] this phrase is not added by the framework so it will be difficult to use it consistently across plugins.
I guess it looks consistent because most help strings are consistently missing. Then again, maybe many of these options are so self explanatory they don’t need a description?

@quba42 thank you. I understand better what you mean.

Our first meeting will be on:
2022-01-18T15:00:00Z2022-01-18T15:30:00Z

All are welcome. I will post the meet link here closer to the day.
If anyone would like a calendar invite from me, send me a DM or ping on Matrix.

We will meet at :

Docs interest group meeting #1
Tuesday, January 18 · 3:00 – 3:30pm (GMT)
Google Meet joining info
Video call link: https://meet.google.com/xad-qvkt-zwy
Or dial: ‪(IE) +353 1 571 1666‬ PIN: ‪174 494 408‬#
More phone numbers: https://tel.meet/xad-qvkt-zwy?pin=5100386652616
Or join via SIP: sip:5100386652616@gmeet.redhat.com

We had our first meeting today.
You can find the minutes here: Better Pulp documentation - HackMD

We will meet again next week at 2022-01-25T13:30:00Z2022-01-25T14:00:00Z

Some general thoughts:

The overall objective would be to have everything a Pulp user needs to set up and work with a particular content type reside within that content type’s plugin docs.

This would lead to a shift in the way pulpcore docs are handled as part of a release.

@ipanova left us with a parting question: for any new feature implemented in core - how to handle what docs are included in Core vs Plugin?

We’re still thinking about that.

Just wanted to respond to one thing mentioned in the minutes, that is installation docs. I am fine with most things living in the plugin docs, the exception being installation docs, which should be in one central place all the plugin docs can reference.

I remember there once were some badly maintained installation docs within the pulp_deb plugin docs. Those confused the hell out of first time users. It also just doesn’t make sense for plugin maintainers to write installation docs since it is perfectly possible to maintain a plugin with very little knowledge of the pulp installer/how to install it. Some installation methods (container) already contain the plugins, so what is there for plugin authors to say? etc. Conceptually I install Pulp and choose a list of plugins to enable, I don’t go out and install the plugin. Just my 2ct.

1 Like

Hey @quba42
I think that we drew largely the same conclusions regarding installation towards the end.

1 Like

Meeting details for today:

Docs working group kickoff meeting
Tuesday, January 25 · 1:30 – 2:00pm
Google Meet joining info
Video call link: https://meet.google.com/xva-efsk-omw
Or dial: ‪(IE) +353 1 571 1763‬ PIN: ‪509 906 482‬#
More phone numbers: https://tel.meet/xva-efsk-omw?pin=6243019267214
Or join via SIP: sip:6243019267214@gmeet.redhat.com

Anyone interested is welcome.

Minutes from a short meeting yesterday : Better Pulp documentation - HackMD

We meet again next week at this time

2022-02-02T13:00:00Z2022-02-02T14:00:00Z

I’ll post a meeting link closer to the time. If you want a calendar invite, DM me an address and I’ll be happy to add you.

Here is our analysis and also our conclusions. Look forward to any feedback:

https://pulpproject.org/2022/02/10/pulp-documentation-sig-findings-and-suggestions/

2 Likes