pdm-backend documentation looks confusingly similar to pdm itself

[vlcinsky]

pdm and pdm-backand are two different products, even though they related one to another closely.

It was very confusing to me that during reading pdm documentation I have found myself in pdm-backend one without noticing.

The problem is, both sides are using almost identical theme.

Proposed solution: use different themes

Change the theme for pdm-backend somehow, e.g. to different color.

It would contribute to more intuitive understanding that pdm differs from pdm-backend and what documentation is currently read.

[pawamoy]

That is understandable, but what you suggest wouldn't be practical IMO. It makes sense to me that documentation of different projects under the same organization use the same theme. What if you have 3, 4, 10 closely related projects, do you have to use 10 different colors?

[vlcinsky]

@pawamoy I guess, it depends on how much we value the documentation reader and his/her ease of understanding it.

Examples of multiple documentations in the same group

Tiangolo

• FastAPI
• Typer
• SQLModel

Using green, black and violet theme.

Using different logo.

Kenneth Reitz

• requests
• Requests-HTML
• Pipenv
• Responder

Mostly using the same theme (incl. colors), but taking care to have large and different logo of the project.

pytest-dev

• pytests
• pluggy

I am not sure, the themes are the same or not, but again, taking care to make the logo clearly different.

The Pallets Projects

• Flask
• Click
• It's Dangerous
• Jinja
• Werkzeug
• MarkupSafe

Often similar theme, but very different (large) logos.

[pawamoy]

I'd say that PDM and PDM-Backend are very closely related, so that's fine as long as they have enough back and forth links between them?

Thanks for the examples. I'm personally not good at creating logos, so cannot help here :stuck_out_tongue:

[vlcinsky]

Links back and forth would not resolve the issue - confused reader.

Changing color of the theme seems sufficient solution to me.

[Wesztman]

Sorry for a sidestep, but on the theme of docs, the docs does not seem to follow the backend releases?

https://backend.pdm-project.org/metadata/#read-from-scm-tag-supporting-git-and-hg

Here I can read about version format, but that function does now seem to be released yet? It's a little confusing.

[frostming]

Sorry for a sidestep, but on the theme of docs, the docs does not seem to follow the backend releases?

https://backend.pdm-project.org/metadata/#read-from-scm-tag-supporting-git-and-hg

Here I can read about version format, but that function does now seem to be released yet? It's a little confusing.

No, we don't plan to use multi-version docs for this simple project, while we may add "added in version x" notes at some point.