Remove sections from README.md

Created on 20 January 2025, 6 months ago

Problem/Motivation

We have duplicate text now, in the README vs on lupus-decoupled.org. IMHO we should replace the sections in the README with a pointer to lupus-decoupled.org.

Prerequisite

All relevant info is actually copied to lupus-decoupled.org before being removed. What was missing: mention of the "Use layout builder" checkbox == https://github.com/drunomics/lupus-decoupled-website/pull/98/files . When that is merged, we're good.

Meta

This isn't super important, but I'd still like a co maintainer to see this / approve / comment, before committing.

We can do this removal, because this 'external' documentation is under our control (and if someone else wants to make changes/additions, there are links on the lupus-decoupled.org website.)

Not in scope for this issue:

Perfecting the README in other ways. (Any info that is not now duplicate, remains in the README - e.g. I haven't touched any mention of "Progressive decoupling".)
The custom_elements project page. I'll start that discussion separately some time.
The question, whether we should have drupal.org handbook pages for Custom elements. (That would duplicate info even further, so it would be an extra argument for removing these things from the README.md, IMHO. If we
want to do that, then this removal is almost a prerequisite.)

(Dis)advantages of removing text from README

Just for completeness -- what came to mind when I was thinking about this:

Advantages of removing:

Less duplicated text to maintain
Dividing things over multiple linked pages IMHO makes it easier for the user to find / concentrate on just the info that they need
and makes it easier for us to provide better examples (as seen in e.g. https://lupus-decoupled.org/get-started/how-it-works which is not in the README or project page).

Disadvantages of removing:

It's less clear, which funtionality is exactly part of the custom_elements module, with the info being spread out over non-grouped pages on lupus-decoupled.org:
- https://lupus-decoupled.org/get-started/how-it-works - only "What is a custom element + Providing custom elements" - the rest about the API is not part of CE module
- https://lupus-decoupled.org/drupal/custom-elements
- https://lupus-decoupled.org/guide/customized-api-output
- https://lupus-decoupled.org/guide/layout-builder (but not "Layout Previews", that's not part of the CE module)
- https://lupus-decoupled.org/drupal/custom-element-processors

The fact that this module's docs are so spread out feels strange, but it's indicative of reality (CE never gets used by itself). IMHO we should just acknowledge this reality (implicitly, by accepting the spread-out-ness) - and the advantages outweigh the disadvantages.

📌 Task

Status

Active

Version

3.0

Component

Documentation

Created by

🇳🇱Netherlands roderik Amsterdam,NL / Budapest,HU

Live updates comments and jobs are added and updated live.

Merge Requests

!110Remove sections from README.md
Open
🇳🇱Netherlands roderik
updated 6 months ago

Comments & Activities

Issue created by @roderik
Merge request !110Remove text from README → (Open) created by roderik
Comment 6 months ago →
🇳🇱Netherlands roderik Amsterdam,NL / Budapest,HU
The build failure (phpunit) is certainly unrelated, I'll check it somewhere else.

(It seems to me that phpunit is only reporting deprecations, in Core code, so it feels like it should exit with warning instead of error....?)
Status changed to Closed: won't fix about 2 months ago8:40am 27 May 2025
Comment about 2 months ago →
🇦🇹Austria fago Vienna
I don't think it makes sense to point to lupus-decoupled in generall, since lupus decoupled does not cover the prgoressive rendering case. I think that little bit of duplication is acceptable.

contrib.social Blog FAQ Discussions

Production build 0.71.5 2024