Open bugfolder opened 2 years ago
A bit more in-depth look at documenting Cards. New pages can be written now and left in draft status; however, existing pages will need to be changed, and those changes should probably not appear until 1.22 is released, to avoid confusing people.
Here's my suggested list of pages to alter and/or add. (Pinging @stpaultim and anyone else who wants to chime in.)
Quick start guide — In addition to replacing the screen shots, I suggest adding a new short section, "The home page", that shows the Cards, gives some brief description, but primarily links to a (new) dedicated sub-page, "The home page".
The home page — this would be a new sub-page of "Using Backdrop", which I suggest comes just after Creating and editing content in the book listing. (The rationale being that you need to know how to create/edit content before you can start tinkering with the home page, but the home page is important enough that it should be high in this list.) That new sub-page should show and talk about Cards, but it should also discuss the other ways of creating home pages (nodes, layouts, views), and should point users to the site information page where the home page is specified.
Creating and editing content — this mentions Posts and Pages, so it needs to be updated to also mention Cards (but again, this can/should be brief; leave the heavy discussion to the new "The home page" page.
Sound reasonable?
@bugfolder - Thanks for looking into this. Without searching for additional places that you might have overlooked, your plans makes sense. Elsewhere, I am seeking access to docs site to help with this.
I've created a draft of The home page mentioned above, here: https://docs.backdropcms.org/documentation/the-home-page. Figures will come later (after the PR is merged and everything is finalized.)
One of the things I realized while writing this is that by giving a fairly detailed description of how the standard installation home page (with Cards) goes together, we're giving the reader a brief, concrete introduction to the concepts of Blocks, Layouts, Views, content types, and Cards, in a way that they can follow along on their own freshly-installed site. So there's value in this that goes beyond the specifics of the home page.
Toward that end, I'd like to suggest some naming changes for the elements of the Card-based home page, to help emphasize to the reader that "these things all work together." For example, the Layout is titled "Home page," which is great. I'd like to see the View take the same approach: instead of calling it "Card grid", how about naming it "Home page Cards".
And instead of givings its display the generic name "Block", how about "Home page Cards block". So that everything that is contributing to the Home page has "Home page" in its name. Yes, this is longer than just "Block", but I think the educational value and clarity it brings to first-time users is worth the extra space (and they can always rename things to be shorter if they don't like the standard names).
Follow-on to https://github.com/backdrop/backdrop-issues/issues/4903. We should document and describe the new Cards content type, with documentation due to appear at the 1.22 release (2022-05-15).
Candidate changes: