docs: reorder interface definition before fetch-libs and link PostgreSQL/library docs in tutorial

Open Beginner friendly
#2,957 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 3 days

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
90/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
postgresql
Domain
documentation

Research direction

Start from the tutorial page source for integrate-your-charm-with-postgresql in the docs tree. Read the two sections named in the issue, then move “Define the charm relation interface” ahead of “Fetch the required database interface charm library”. Add the PostgreSQL integration/Charmhub and data_interfaces reference links where those terms are introduced. Done when the page renders in the new order with working outbound links and no added prose.

Written by the indexing model from the issue text.

Description

Target Page

https://canonical.com/juju/docs/ops/latest/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/integrate-your-charm-with-postgresql/

Observation

In keeping with Diátaxis tutorial principles (clear cause-and-effect sequence and outbound links to Reference/How-to docs rather than inline explanation), the first two sections of this page currently work in reverse order and omit the relevant outbound links:

  1. Inverted dependency order: Fetch the required database interface charm library introduces data_platform_libs.data_interfaces before Define the charm relation interface introduces the provider charm and interface:

    "First, find out the name of the interface that PostgreSQL offers for other charms to connect to it. According to the documentation of the PostgreSQL charm, the interface is called postgresql_client."

    Because the dependency flows from postgresql-k8s → postgresql_client → data_interfaces, defining the requires endpoint first makes the reason for fetching data_interfaces self-evident without adding prose.

  2. Missing outbound links: Neither "the documentation of the PostgreSQL charm" nor data_platform_libs.data_interfaces is linked when introduced (the Charmhub URL for data_interfaces only appears later inside a code comment under Add relation event observers).

Proposed Change
  1. Move Define the charm relation interface before Fetch the required database interface charm library.
  2. Link "the documentation of the PostgreSQL charm" to Charmed PostgreSQL – Integrate (or postgresql-k8s integrations), and link data_platform_libs.data_interfaces to its Charmhub library page and/or the Interface libraries reference.

Reported from: https://canonical.com/juju/docs/ops/latest/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/integrate-your-charm-with-postgresql/

Dominant language
Python
Stars
267
Forks
156
Avg merge
5d 5h
Merged PRs (30d)
43

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from canonical/operator

All issues in canonical/operator

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.