docs: refactored _setting up container registries_

[themr0c]

What does this PR do?

• Refactored all Podman registries procedures into a single page: Setting up container registries (including redirections).
• Rewritten following the Tutorial template and guide from The Good Docs project. See https://gitlab.com/tgdp/templates/-/tree/main/tutorial?ref_type=heads. (Learning based rather than task oriented)
• Added: Changing your registry credentials, Removing a registry configuration.
  Understanding the registry configuration.

Screenshot/screencast of this PR

What issues does this PR fix or reference?

How to test this PR?

[deboer-tim]

I really like the tone of the tutorial and think it is clean and well written - but I have to admit I wasn't expecting it to mean that all previous content on the topic would be removed (replaced by the tutorial).

My only real concern is whether a user on any particular OS who (e.g.) 'just wants to setup a registry' will be able to easily find and consume that particular snippet of content in the middle of the tutorial, or whether there are some parts of the tutorial we should keep as direct how-to content. Might need to sleep on it or get other opinions.

[themr0c]

I don't understand. It was clearly stated in the initial Gdoc that the intent was to replace the current content.

[cdrage]

I really like the tone of the tutorial and think it is clean and well written - but I have to admit I wasn't expecting it to mean that all previous content on the topic would be removed (replaced by the tutorial).

My only real concern is whether a user on any particular OS who (e.g.) 'just wants to setup a registry' will be able to easily find and consume that particular snippet of content in the middle of the tutorial, or whether there are some parts of the tutorial we should keep as direct how-to content. Might need to sleep on it or get other opinions.

I agree with Tim.

I do not think the tutorial is an improvement but rather makes it more confusing, I liked how we had tabbed sections for Windows / Linux / macOS as it differentiated between the three, but now it's in a bullet point form again (how it was previously) to showcase the differences.

[slemeur]

We are leaning toward a form of documentation that is less of an "instructional tone" to be more guided and end-goal centric. Going that direction is also about making the documentation more approachable and informative, but still providing clear step-by-step instructions. The content is structured to facilitate ease of understanding with a user-friendly tone which will result in a more engaging documentation.

The issue we have with the current organization of the documentation is that we have a lot of pages and sub-ages and it makes it particularly hard to read through it or to find information.
With the changes introduced by @themr0c we are addressing that issue. Now all content related to the registries are in a single page. Easier for the reader, easier for the maintainer.

We could improve the way we separate information depending on the platform. We could integrate inline tabs per OS, each time we have different instructions for each platform.
Example:
This:

Could be:

[mairin]

I really prefer this form of writing the docs; the language and way it's approached feels friendlier and more accessible. This is excellent work @themr0c !

Some UX-minded suggestions:

• Back to top link for sections? I like the anchor links under "what you will gain" - it might be nice to have a "top" or ⬆️ link at the level of the section header of the content the anchor links to. I know we have the section links on the right-hand side as well, but if you use the "what you will gain" section to navigate, this back to top piece feels missing.

• Sidebar some of the meta content This is sheerly a visual design thought... maybe pulling out the content like who is this for and what you will need as a sidebar that float on the side, just to visually distinguish between the content and the meta content. Could also maybe place the meta content in a collapsible box? Or some how style it different. I can do a mockup with some ideas.

[themr0c]

Updated with tabs.

[themr0c]

NB: Vale errors are mistakes, see #4498.

[slemeur]

Looks better with the tabs for me

[themr0c]

Updated teh overview section. @slemeur @deboer-tim is that mergeable now?

[deboer-tim]

Vale is so chatty and verbose it's hard to see what you changed in each commit, that's probably something we should address separately. :-( You'll also need to make it happy to pass PR checks.

+1 to removing 'Who this is for'. It kind of feels like it just got merged into the overview though, which is getting a bit long IMHO. I would prefer to just remove the first two paragraphs - the first is generic and applies to everything in PD, the second is basically what was in the 'who is this for' and anyone looking for this doc will already know it's for them (or it's evident from the rest of the overview).

I would really like to simplify the titles so that I can scan the list on the right to jump to a specific section. e.g. right now most of them start with 'Setting up a'/'Verifying your' so it's hard to quickly find a section like 'insecure registry'.

[themr0c]

I am not ready to give up on effective titles starting with a gerund. This is a good rule.
A section named "unsecure registry" would make sense to you, who know the app and the feature, but would be unclear for the intended audience.

[slemeur]

The intro has to be more direct and easy to scan.
Most of the time, the reader will come to the page, with "one need". With the current state, we are requiring the reader to read a long set of sentences to "identify" what's in the documentation page. It's not efficient.

Titles are also redundant and must more direct.

[slemeur]

if easier - we could consider removing the overview paragraph.

[themr0c]

Can we stay with what we agreed on last Thursday, avoid another round of changes, and merge as good enough, please?

[deboer-tim]

I am not ready to give up on effective titles starting with a gerund. This is a good rule. A section named "unsecure registry" would make sense to you, who know the app and the feature, but would be unclear for the intended audience.

"Setting up insecure registries" or "How to setup an insecure registry" provides zero additional value or clarity to the intended audience. If they're scanning for words like 'insecure' or 'authentication', it's hurting them because they need to read twice as many words to find what they're looking for.

Take a look at some random docs from equivalent sites - no gerund, just succinct titles:

• Docker: https://docs.docker.com/build/guide/multi-stage/
• VS Code: https://code.visualstudio.com/docs/terminal/shell-integration
• IntelliJ: https://www.jetbrains.com/help/webstorm/working-offline.html

[themr0c]

Gerund or not, the presence of a verb to start a procedure title is a well-established convention.

The two shared Docker and IntelliJ docs examples are inconsistent outliers in documentation sets that are following this convention. See in other pages: "Build the image", "Run the container", "Add stages", "Speed up indexing", etc.

Stripe docs have an excellent reputation, and follow the same rule. For example: https://stripe.com/docs/development/quickstart

The VSCode docs have a reputation to be generally inconsistent, and are not an example to follow for good practice.

[deboer-tim]

I didn't hunt for outliner pages, those were just the first ones I found that had lots of topics. Personally I find Stripe wordy. But either way, all of these examples have much shorter titles without repetition.

[themr0c]

@deboer-tim ^ some proposals to get titles shorter.

[slemeur]

LGTM !

[themr0c]

Wow, local rebase required to pass format linter test did reset all commit dates, strange.

[themr0c]

@slemeur @deboer-tim @benoitf I am missing the authority to validate Argos changes. Can you please provide me the accreditation?

[benoitf]

@themr0c argos is not a required check (but you should have received a message long time ago to join an argos team)