Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update and align template descriptions #36000

Merged
merged 9 commits into from
Nov 30, 2021
Merged

Conversation

jameskoster
Copy link
Contributor

@jameskoster jameskoster commented Oct 27, 2021

Now that we're beginning to get a better understanding for where these descriptions will appear, we can begin to refine them.

This PR makes the language used across descriptions consistent, and in some cases significantly shortens them.

Template Before After
Index The default template used when no other template is available. This is a required template in WordPress. Displays posts.
Home Template used for the main page that displays blog posts. This is the front page by default in WordPress. If a static front page is set, this is the template used for the page that contains the latest blog posts. Displays as the site's home page, or as the Posts page when a static home page it set.
Front Page Template used to render the front page of the site, whether it displays blog posts or a static page. The front page template takes precedence over the "Home" template. Displays as the site's home page.
Singular Template used for displaying single views of the content. This template is a fallback for the Single, Post, and Page templates, which take precedence when they exist. Displays a single post or page.
Single Post Template used to display a single blog post. Displays a single post.
Page Template used to display individual pages. Displays a single page.
Archive The archive template displays multiple entries at once. It is used as a fallback for the Category, Author, and Date templates, which take precedence when they are available. Displays post categories, tags, and other archives.
Author Archive template used to display a list of posts from a single author. Displays latest posts written by a single author.
Category Archive template used to display a list of posts from the same category. Displays latest posts in a single post category.
Taxonomy Archive template used to display a list of posts from the same taxonomy. Displays latest posts from a single post taxonomy.
Date Archive template used to display a list of posts from a specific date. Displays posts from a specific date.
Tag Archive template used to display a list of posts with a given tag. Displays latest posts with a single post tag.
Search Template used to display search results. Displays search results.
Privacy Policy na Displays the privacy policy page.
404 Template shown when no content is found. Displays when no content is found.

Before

Screenshot 2021-10-27 at 13 48 42

After

Screenshot 2021-10-27 at 14 11 53

Some of the changes are simple optimisations. Others are more profound, like the Index template. In php themes, it is standard practise for the index template to serve as a fallback by programatically detecting if the visitor has requested an archive or a single post, and then acting accordingly. In the block theme paradigm this is not possible, making the Index template more singular in its purpose.

@jameskoster jameskoster added [Feature] Full Site Editing Needs Copy Review Needs review of user-facing copy (language, phrasing) labels Oct 27, 2021
@jameskoster
Copy link
Contributor Author

Perhaps this is an appropriate place to discuss the Index template :) Fleshing out those thoughts a little more...

In the WP template hierarchy, Index is used as a fallback when any of the following templates do not exist:

  • Archive
  • Singular
  • Home
  • 404
  • Search

In php themes it is capable of fulfilling this role by including logic to determine what the visitor has requested on-the-fly.

In block-theme world, this doesn't work so well because the template cannot contain this logic. Consider a block theme that only supplies an Index template...

  • If you visit an archive, you'll see the appropriate posts ✅
  • If you search, you'll see the appropriate posts ✅
  • If you visit a single post or page, you'll see the query format from Index, containing that single post. So unless that format displays the full post content (many only display the excerpt), it's not possible to actually view the full post / comments etc ❌
  • If you visit a page that cannot be found (404), you will see just the header and footer ❓

All that to say, in block-theme world the Index template takes on a more singular purpose, so perhaps it can have a more intuitive name when it appears in the UI?

Essentially, Index is useful for:

  • Acting as a fallback when no Archive template exists.
  • Displaying latest posts either:
    • When the homepage is configured to display latest posts.
    • A static homepage is set, but a posts page is specified.

In that light, perhaps Index can simply be called "Posts"? This would make the minimum required posts for a block theme:

  • Posts
  • Singular (or single + page)
  • 404

Which seems a little more intuitive than the current setup.

@kjellr
Copy link
Contributor

kjellr commented Oct 28, 2021

If you visit a single post or page, you'll see the query format from Index, containing that single post. So unless that format displays the full post content (many only display the excerpt), it's not possible to actually view the full post / comments etc ❌

Isn't that the case with classic themes too, though? If my theme was just an index.php template that used the_post_except(), that's all that would be shown on a single post page.

Either way, I think the "Posts" framing makes sense. index is such a technical term — I'm not sure it'll make sense to users otherwise.

@SeywardDarby
Copy link

Editorial here. Sorry for the delay in sending notes. Here they are, in bold.

INDEX
Note: It seems like there's still some discussion about how to frame this. My 2 cents is that this works: "Posts / Displays latest posts."

HOME
Edit: "Default home page displaying latest posts. If the Front Page template is used to set a static home page, this becomes the template for the Posts page."

SINGULAR
Note: So Singular only displays when neither Single (Post) nor Page is in use? In that case, I would suggest, "Default template for displaying a single piece of content when the Post or Page template isn't in use."

SINGLE
Edit: Change the name of this template to "Post"
(FWIW, if you do this, you can also change "Singular" to "Single"—which sounds better anyway!)

FRONT PAGE:
Edit: "Displays as the site's home page."

CATEGORY:
Edit: "Displays latest posts in a single category."

TAG
Edit: "Displays latest posts with a single post tag."

@jameskoster
Copy link
Contributor Author

Isn't that the case with classic themes too, though? If my theme was just an index.php template that used the_post_except(), that's all that would be shown on a single post page.

That is indeed the case, but I don't think anyone building a theme for general consumption would do that? The wp.org theme review guidelines say this about Index:

If you only include this template file [Index], it must include all functionality of your theme.

Since block templates cannot perform any logic, it would not be possible for index.html to "include all functionality" of the theme. Therefore, a block theme consisting of only index.html wouldn't really work for a typical WordPress site, and consequently I don't suppose such a theme would be acceptable in the theme directory.

@jameskoster
Copy link
Contributor Author

jameskoster commented Nov 2, 2021

@SeywardDarby Thank you! A couple of thoughts:

Default home page displaying latest posts. If the Front Page template is used to set a static home page, this becomes the template for the Posts page.

I'm not sure that this description for the Home template is quite right.

Home becomes the template for the posts page regardless of whether the Front Page template exists or not. Perhaps we could revise:

Default template for displaying latest posts. If the home page is set to a static home page, Home becomes the template for the Posts page.

This still doesn't feel quite right though... for that second use case, "Home" feels like a really contradictory name. I wonder if we can come up with something better. This all kind of ties in with the discussion around the Index template. In the block theme world, I'm not really sure we need both Index and Home – they're both serving the same purpose. We may need to work on these two particular templates in isolation.

So Singular only displays when neither Single (Post) nor Page is in use?

Singular will only ever be used if Single or Page don't exist at all. It's useful when a theme author wants to use the exact same template for posts and pages. So perhaps this can just be:

Default template to display a single post or page.


Changing "Single" to "Post" makes sense to me. Edit: Just remembered that we already updated the name of this one to "Single Post" :D

@jameskoster
Copy link
Contributor Author

jameskoster commented Nov 2, 2021

Perhaps a better way to frame Index / Home:

Index will resolve to display any archive when archive.html is not present, IE it may not always be latest posts. So we could give it a non-specific name like "Posts", and a very simple description:

Displays posts.

The unique feature of the home template is that it will always display latest posts, whether that is because it resolves for the homepage, or the posts page when a static page is set as the homepage. So perhaps we can call the home template "Latest posts" with the description:

Displays as the site's home page, or as the Posts page when a static home page it set.

Co-authored-by: Carolina Nymark <hi@themesbycarolina.com>
@shaunandrews
Copy link
Contributor

I love seeing these become shorter and more succinct. However, I do wonder if there's some way to avoid and reduce the repetitious use of the word "Displays" for every template description.

image

@jameskoster
Copy link
Contributor Author

Yeah it would be good to optimise that. We can probably lose the "Displays" prefix for the list view use case:

Screenshot 2021-11-08 at 18 08 47

But we'd need to account for other areas in which the description appears too. Obviously this doesn't work very well:

Screenshot 2021-11-08 at 18 10 07

@SeywardDarby
Copy link

Hi. Sorry to be slow to chime back in here. If you would like me to review revised text, please let me know and point me to the latest version (ideally in a Google doc if one exists/can be made). One thought for the list view: The shortened versions could work well, but we'd need to be consistent about the grammar and syntax, and singular versus plural. For instance, right now we have "Page: Individual Pages" and "Single: A single blog post," which aren't stylistically consistent. Something like "Page: A single page" and "Post: A single blog post" would be consistent.

Again, please let me know if you would like me to review revised text in full. Thanks!

@jameskoster
Copy link
Contributor Author

The descriptions in the OP are the latest versions :)

I think it will be tricky to eliminate the repetitious "Displays..." prefix and still have the descriptions adaptable to different contexts.

@SeywardDarby
Copy link

OK. A few questions:

  • Is it possible to have different descriptions for different locations, or do they need to be standardized? (e.g. could you have "Displays a single page" in one place, and "A single page" in another place?)
  • Would it be possible to interchange terms such as "show" and "present" with "display," or is "display" the only verb that works in this context?

@jameskoster
Copy link
Contributor Author

I think it's possible, but would need a dev to confirm. The trade-off is there's twice as much to translate. I don't know if it's worth it.

Would it be possible to interchange terms such as "show" and "present" with "display," or is "display" the only verb that works in this context?

Sure. Words like 'display' and 'render' appear quite a lot in the current template documentation. I suppose 'render' is technically the correct term, but I figured 'display' was more user-friendly. Perhaps it's ok to use 'render' though, seeing as template editing is a more advanced feature. Of course 'show' and 'present' work too :D

Copy link
Contributor

@carolinan carolinan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Describing the index is tricky, but I think displaying posts is the most common result when the index is used as a fallback.

@jameskoster
Copy link
Contributor Author

We can continue to refine. If this makes it in to the beta we'll hopefully get feedback :)

@jameskoster jameskoster merged commit be69047 into trunk Nov 30, 2021
@jameskoster jameskoster deleted the update/template-descriptions branch November 30, 2021 10:34
@github-actions github-actions bot added this to the Gutenberg 12.1 milestone Nov 30, 2021
@youknowriad
Copy link
Contributor

I noticed that the descriptions on Core are different from these ones. Please don't forget to add the "backport to WP beta/RC" label in 5.9 targeted PRs otherwise, these changes will get lost in the future.

@youknowriad youknowriad added the Backport to WP 6.7 Beta/RC Pull request that needs to be backported to the WordPress major release that's currently in beta label Dec 6, 2021
@youknowriad youknowriad removed the Backport to WP 6.7 Beta/RC Pull request that needs to be backported to the WordPress major release that's currently in beta label Dec 7, 2021
@Mamaduka Mamaduka mentioned this pull request Dec 7, 2021
7 tasks
@youknowriad youknowriad added the Backport to WP 6.7 Beta/RC Pull request that needs to be backported to the WordPress major release that's currently in beta label Dec 9, 2021
@youknowriad
Copy link
Contributor

I added the label back to sync the wp/trunk branch. (this is already in core now)

@noisysocks noisysocks removed the Backport to WP 6.7 Beta/RC Pull request that needs to be backported to the WordPress major release that's currently in beta label Dec 13, 2021
noisysocks pushed a commit that referenced this pull request Dec 13, 2021
* Update and align template descriptions

* More refinements

* Update descriptions

* More updates

* Optimise!

* Localize privacy policy description

Co-authored-by: Carolina Nymark <hi@themesbycarolina.com>

* Descriptions

Co-authored-by: Carolina Nymark <hi@themesbycarolina.com>
@paaljoachim
Copy link
Contributor

@jameskoster is working on updating the template names in this PR:
#51428
Head on over and take a look and give some feedback.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Needs Copy Review Needs review of user-facing copy (language, phrasing)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants