Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: refactor Authenticating to container registries. #5109

Closed
themr0c opened this issue Dec 4, 2023 · 0 comments · Fixed by #4965
Closed

docs: refactor Authenticating to container registries. #5109

themr0c opened this issue Dec 4, 2023 · 0 comments · Fixed by #4965
Assignees
Labels
area/documentation 📖 kind/enhancement ✨ Issue for requesting an improvement

Comments

@themr0c
Copy link
Contributor

themr0c commented Dec 4, 2023

Is your enhancement related to a problem? Please describe

Current state
3 pages:

  1. Registries / Working with container registries
  2. Authenticating to a registry / Authenticating to a pre-configured registry
  3. Adding an insecure registry / Adding an Insecure Registry to Podman Desktop

Problems:

  1. Not indexed by Google: https://podman-desktop.io/docs/containers/registries - Reason: “Crawled - currently not indexed”. Probably because of too sparse content.
  2. Most probably useful content is in (2), would be better in (1).
  3. Inconsistencies: working / authenticating to / adding?
  4. Missing good practice direction: default action vs. advanced / alternate.
  5. Missing one story: adding a (secure) custom registry.

Describe the solution you'd like

  1. Documentation strategy is following a new direction: aim for learning-oriented tutorials rather than task oriented how-tos.
  2. Therefore, define the content structure following the Tutorial guide and Tutorial template from The Good Docs Project.
  3. Differentiate clearly between the documentation states:
    1. Define the intent and the outline in a collaboration platform enabling comments and suggestions, such as Gdoc: https://docs.google.com/document/d/1fGXU_DkfN_O80KRZlIAX_38AU2ncRUJBMKDWoGxOkI0/edit.
    2. Draft the content in Markdown native collaboration platform such as HackMd: https://hackmd.io/g96tN9zGRpuPdggYVMLXgg#.
    3. Finalize in a pull request.

New outline that has been accepted:

  1. A single page, with sections:
    10. Overview
    11. Before you start
    12. Setting up a pre-configured container registry
    13. Setting up a custom container registry
    14. Setting up a custom container registry with an insecure certificate
    15. Verifying your registry is properly configured
    16. Changing your registry credentials
    17. Removing a registry
    18. Understanding the registry configuration
    19. Next steps

Describe alternatives you've considered

Rejected proposals:

(Discussed in https://docs.google.com/document/d/1fGXU_DkfN_O80KRZlIAX_38AU2ncRUJBMKDWoGxOkI0/edit)

New outline, proposal 1:

(A) Setting up pre-configured registries
(B) Setting up custom registries <Tabs: Windows, macOS, Linux>
<Optional step: when the registry has an insecure certificate, such as a self-signed certificate>
Outline explanation:
Merge (2) into (1) -> (A): “Setting up pre-configured registries”.
(3) -> (B) “Setting up custom registries”, with the “insecure registries” as optional steps (

)
Keep 2 pages to avoid nested tabs: (B) already has tabs.

New outline, proposal 2:

Reduce into a single page by using optional steps rather than tabs:
(A) Setting up registries: with 2 optional steps

<Optional step: when the registry has an in

Additional context

No response

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/documentation 📖 kind/enhancement ✨ Issue for requesting an improvement
Projects
Archived in project
Development

Successfully merging a pull request may close this issue.

3 participants