backdrop-ops / docs.backdropcms.org

Website for displaying Backdrop CMS documentation and API source code.
https://docs.backdropcms.org/
6 stars 6 forks source link

Add documentation for new Cards content type #192

Open bugfolder opened 2 years ago

bugfolder commented 2 years ago

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:

bugfolder commented 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.)

Sound reasonable?

stpaultim commented 2 years ago

@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.

bugfolder commented 2 years ago

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).