[blog] Simplify the labels #30921

oliviertassinari · 2022-02-05T14:20:46Z

This is an attempt to improve the blog post labels structure. I have documented in https://www.notion.so/mui-org/Blog-247ec2bff5fa46e799ef06a693c94917 was could make sense for 1. when to use each label so authors know what to apply and 2. why we have these labels, so we know how to change them.

We do the following simplification

Company update -> Company
Team -> Company

https://deploy-preview-30921--material-ui.netlify.app/blog/

A side note: the pagination should be using <a>, not buttons. This is really important for SEO. Each post should be crawlable

oliviertassinari · 2022-02-05T14:21:00Z

docs/lib/sourcing.ts

@@ -13,7 +13,7 @@ export interface BlogPost {
  title: string;
  description: string;
  image?: string;
-  tags?: Array<string>;
+  tags: Array<string>;


force to always have tags

oliviertassinari · 2022-02-05T14:21:12Z

docs/lib/sourcing.ts

@@ -30,6 +30,10 @@ export const getBlogPost = (filePath: string): BlogPost => {
  };
 };

+// Avoid typos in the blog markdown pages.
+// https://www.notion.so/mui-org/Blog-247ec2bff5fa46e799ef06a693c94917
+const ALLOWED_TAGS = ['MUI Core', 'News', 'MUI X', 'Company', 'All products'];


Feels like this:

oliviertassinari · 2022-02-05T14:21:33Z

docs/packages/markdown/parseMarkdown.js

-    headers.components = [];
+    return headers;
+  } catch (err) {
+    throw new Error(`${err.message} in getHeader(markdown) with markdown: \n\n${header}`);


Feels like:

oliviertassinari · 2022-02-05T14:23:36Z

docs/pages/blog/danail-hadjiatanasov-joining.md

@@ -4,7 +4,7 @@ description: We are excited to share that Danail Hadjiatanasov has joined MUI as
 date: 2020-10-23T00:00:00.000Z
 authors: ['oliviertassinari']
 card: true
-tags: ['Team']
+tags: ['Company', 'MUI X', 'News']


Implements the proposals from https://www.notion.so/mui-org/Improve-blog-infrastructure-bcae2b15493f4daba0758adf499f7793#c777a90341e0489fab4ba9414a60e995

mui-bot · 2022-02-05T14:24:27Z

No bundle size changes

Generated by 🚫 dangerJS against 4295cb5

mbrookes · 2022-02-05T17:13:10Z

Something's off with the logic, "All products" is returning posts that aren't tagged with it:

But I'm not sure if "All products" is even necessary. Posts that cover both MUI X and Core simply need both those tags.

Also, I'm not sure about tagging hiring posts with the product tag. If I select "MUI X" I expect posts about MUI X, not company news.

mbrookes · 2022-02-05T17:22:35Z

It also feels like anything tagged "Company" should also be tagged "News", but that isn't currently always the case.

oliviertassinari · 2022-02-06T16:15:39Z

Something's off with the logic, "All products" is returning posts that aren't tagged with it:

@mbrookes It returns blog posts that have any of the product tags. Based on this logic, it works as expected.

Now, is the expectation clear? This is another problem. The purpose of the tag is to be able to remove posts that don't cover the product, typically posts about the company, e.g. retreat, Material-UI -> MUI org rename, fundraising announcement. There might not be a lot.

But I'm not sure if "All products" is even necessary. Posts that cover both MUI X and Core simply need both those tags.

My assumption is that we will get more than these two product labels. But we would also get: MUI Studio, MUI Base, MUI Design kits, etc. So that we would need some way to have a hierarchy of product labels.

Also, I'm not sure about tagging hiring posts with the product tag. If I select "MUI X" I expect posts about MUI X, not company news.

I feel you. I have been torn internally about this problem. I went for a different approach: MUI X is not directly about the product. It's about what impacts it: https://www.notion.so/mui-org/Blog-247ec2bff5fa46e799ef06a693c94917

What I want to reproduce is this UX: https://www.hashicorp.com/blog/products/packer, for each product. We need to label each blog post for this. What I would argue is that Damien joining the MUI X team is about MUI X. The audience that cares about MUI X would want to know they is a new maintainer (back then, with a small team it mattered, now, less). No objections to removing this label though.

It also feels like anything tagged "Company" should also be tagged "News", but that isn't currently always the case.

I'm happy with removing the "News" label if we can't get a common understanding of what this label is about => most people won't either => useless.

Please advise.

mbrookes · 2022-02-07T20:44:51Z

Based on this logic, it works as expected.

It's titled 'Posts tagged as "All products"', but returns posts that aren't tagged as "All products", so it's illogical, and doesn't work as expected. Tags have an implicitly understood behaviour, which this is breaking. It leads to poor UX.

I'd vote to get rid of the "All products tag". Realistically, visitors will be interested in a particular product.

No objections to removing this label though.

Deal.

I'm happy with removing the "News" label if we can't get a common understanding of what this label is about

I would assume that anything about the company is news, but not all news is about the company.

danilo-leal · 2022-02-07T21:09:20Z

My thoughts on the current state:

Agree with removing the "All products" tag.
I'd leave the product tags for product information only, not using them for disclosing if a new person joined its team or similar.
To tackle the News ambiguity, maybe Announcement is a better word?! It seems more straightforward. It would be used whenever new things are introduced or when things change significantly.
- Examples:
  - Introducing MUI Core v.5.0.0: announcement, MUI Core.
  - Q3 2021 update: company.

oliviertassinari · 2022-02-16T14:29:33Z

I have pushed a new commit that implements @samuelsycamore's ideas. It's doing the synthesis between:

https://stripe.com/blog, recognizing the superiority of keeping things simple 👌:

We can add an "Engineering" tag in the future if we struggle to hire but considering our product, I doubt it. It would be used for blog posts like https://stripe.com/blog/globe or the one we have in #28362. Maybe more for fun.

It prepares the space with a new product: field. In the future, we can grow it to something like Hasicorp is doing 👌 https://www.hashicorp.com/blog/hashicorp-cloud-platform-adds-new-asia-regions-mfa-and-more

It includes a "News" label. We have a very limited use case for it today. Very few blog posts don't have this label. However, we are anticipating our content strategy growth plan. We will create a lot more evergreen SEO content. This tag is going to be important.

It seems to be a great synthesis of the concerns that everyone has.

I would assume that anything about the company is news, but not all news is about the company.

@mbrookes IMHO, the year in review is not really news. We usually don't announce anything new.

To tackle the News ambiguity, maybe Announcement is a better word?!

@danilo-leal The downside is that it's much longer. I have seen it used in https://www.netlify.com/blog/news/.

A side thought: https://www.netlify.com/blog/2021/12/31/serving-custom-http-headers/ I think that this is crap. Spent the same amount of time to polish the docs, you will be way better off. Or create a proper tutorial, not a blog post!

mapache-salvaje · 2022-02-16T15:36:51Z

Looks good to me! I like the product: field, as I think that achieves the same effect you were going for with the individual product tags, but without the additional clutter, or the ambiguity of the "All products" tag.

oliviertassinari · 2022-02-16T15:41:14Z

field, as I think that achieves the same effect you were

Potentially. For now, it's a dead property. I think that it's with the studio that we will really feel the pain, enough to make us want to have isolation.

danilo-leal · 2022-02-16T15:48:20Z

I wonder if using Product for the developer survey is the best way to go. It's quite handy to have a tag for the survey. Any thoughts?

mapache-salvaje · 2022-02-16T15:54:42Z

@danilo-leal the only issue I see there is that a survey tag may be too granular—if it only gets used once or twice per year, then I'm not sure that it deserves its own category.

mbrookes · 2022-02-17T21:24:16Z

I have pushed a new commit that implements @samuelsycamore's ideas.`

Unless I'm missing something, Sam hadn't commented before this?

For now, it's a dead property.

Then let's do what @danilo-leal and I suggested, and remove it in favour of the product specific ones.

IMHO, the year in review is not really news.

But the quarterly reviews are?

oliviertassinari · 2022-02-17T21:41:34Z

Unless I'm missing something, Sam hadn't commented before this?

@mbrookes We have chatted about it during a meeting.

Then let's do what @danilo-leal and I suggested, and remove it in favour of the product specific ones.

@mbrookes Yes, already removed 👍 .

But the quarterly reviews are?

@mbrookes We announce the latest features that were released in the quarterly blog posts and what will come next. Hence why I thought about it.

Maybe we should have this strategy: always apply "News" unless it's obvious that it's not a news or an announcement (https://www.notion.so/mui-org/Blog-247ec2bff5fa46e799ef06a693c94917). Would this work? It would still solve the main problem: make it possible to filter out SEO evergreen blog posts.

mbrookes · 2022-02-18T18:44:32Z

Yes, already removed

No, it has been renamed "Product" and the logic fixed. The product specific ones have been removed. It's the opposite of what @danilo-leal and I suggested.

We announce the latest features that were released in the quarterly blog posts and what will come next.

It's the same in the annual blog post: 2021 in review and beyond. Either all of them are news, or none of them are.

always apply "News" unless it's obvious that it's not a news or an announcement

As long as it's consistent.

oliviertassinari · 2022-02-20T23:43:59Z

So it seems that there is no agreement on the right way to handle these tags. At least, it's not clear to me what each person envisions as the best nor why.

Therefore, I have reduced the ambition of this PR to unlock it. I have followed what seems to be an overall consensus. The baseline assumption is that a low number of tags = better. It's better because it improves the UX, because it's less operational overhead. Based on this assumption, there is a quick-win: "Company updates" and "Team" are about the company, so we can rename both to "Company". Does it work, can we merge?

Thinking more about this problem, I have noticed something wrong with our terminology. What we have implemented as "tags" with the filtering is AFAIK normally called "categories"(I assume dating pre-WordPress). https://www.oncrawl.com/oncrawl-seo-thoughts/optimise-blog-categories-tags/ goes into more detail about why. They are meant to create horizontal cross-categories links, while categories are meant to create a vertical structure for readers to quickly filter out content. @samuelsycamore I would speak under your control, is this accurate?

I have made a proposal in https://www.notion.so/mui-org/Blog-SEO-structure-897c1ad742ec4274838a10f4bd6b3e3a for what I think we should do next. Please challenge, or create alternative options.

It's the same in the annual blog post: 2021 in review and beyond. Either all of them are news, or none of them are.

@mbrookes I don't feel the same way about it. The quarter update covers changes with a 3 months lense, the yearly update achieves the same with a one-year lense. The former is x4 lot more granular about the recent past and close future than the latter. In practice, it means that quarterly blog posts can do announcements, while the yearly review focuses more on the past, it's a review. What I have felt is that we miss a https://mui.com/blog/2021-q4-update/ blog post. But it's not important.

oliviertassinari · 2022-02-27T22:32:01Z

Bump

oliviertassinari added the blog label Feb 5, 2022

oliviertassinari force-pushed the simplify-labels branch from 84af4d9 to dbd09d9 Compare February 5, 2022 14:22

oliviertassinari commented Feb 5, 2022

View reviewed changes

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Feb 6, 2022

oliviertassinari force-pushed the simplify-labels branch from ab249ca to 116acae Compare February 6, 2022 15:59

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Feb 6, 2022

oliviertassinari requested review from mbrookes and danilo-leal February 6, 2022 16:17

oliviertassinari requested a review from mapache-salvaje February 16, 2022 14:35

oliviertassinari added 3 commits February 20, 2022 23:12

[blog] Simplify the labels

726ae31

ignore types

bd6029f

revery tag changes

7c953de

oliviertassinari force-pushed the simplify-labels branch 3 times, most recently from 04fa5c5 to 35d1407 Compare February 20, 2022 22:23

simpler change

4295cb5

oliviertassinari force-pushed the simplify-labels branch from 35d1407 to 4295cb5 Compare February 20, 2022 22:25

oliviertassinari merged commit 21d1f49 into mui:master Mar 5, 2022

oliviertassinari deleted the simplify-labels branch March 5, 2022 11:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[blog] Simplify the labels #30921

[blog] Simplify the labels #30921

oliviertassinari commented Feb 5, 2022 •

edited

Loading

oliviertassinari Feb 5, 2022

oliviertassinari Feb 5, 2022

oliviertassinari Feb 5, 2022

oliviertassinari Feb 5, 2022

mui-bot commented Feb 5, 2022 •

edited

Loading

mbrookes commented Feb 5, 2022

mbrookes commented Feb 5, 2022

oliviertassinari commented Feb 6, 2022 •

edited

Loading

mbrookes commented Feb 7, 2022

danilo-leal commented Feb 7, 2022

oliviertassinari commented Feb 16, 2022 •

edited

Loading

mapache-salvaje commented Feb 16, 2022

oliviertassinari commented Feb 16, 2022

danilo-leal commented Feb 16, 2022

mapache-salvaje commented Feb 16, 2022

mbrookes commented Feb 17, 2022 •

edited

Loading

oliviertassinari commented Feb 17, 2022 •

edited

Loading

mbrookes commented Feb 18, 2022 •

edited

Loading

oliviertassinari commented Feb 20, 2022 •

edited

Loading

oliviertassinari commented Feb 27, 2022

[blog] Simplify the labels #30921

[blog] Simplify the labels #30921

Conversation

oliviertassinari commented Feb 5, 2022 • edited Loading

oliviertassinari Feb 5, 2022

Choose a reason for hiding this comment

oliviertassinari Feb 5, 2022

Choose a reason for hiding this comment

oliviertassinari Feb 5, 2022

Choose a reason for hiding this comment

oliviertassinari Feb 5, 2022

Choose a reason for hiding this comment

mui-bot commented Feb 5, 2022 • edited Loading

mbrookes commented Feb 5, 2022

mbrookes commented Feb 5, 2022

oliviertassinari commented Feb 6, 2022 • edited Loading

mbrookes commented Feb 7, 2022

danilo-leal commented Feb 7, 2022

oliviertassinari commented Feb 16, 2022 • edited Loading

mapache-salvaje commented Feb 16, 2022

oliviertassinari commented Feb 16, 2022

danilo-leal commented Feb 16, 2022

mapache-salvaje commented Feb 16, 2022

mbrookes commented Feb 17, 2022 • edited Loading

oliviertassinari commented Feb 17, 2022 • edited Loading

mbrookes commented Feb 18, 2022 • edited Loading

oliviertassinari commented Feb 20, 2022 • edited Loading

oliviertassinari commented Feb 27, 2022

oliviertassinari commented Feb 5, 2022 •

edited

Loading

mui-bot commented Feb 5, 2022 •

edited

Loading

oliviertassinari commented Feb 6, 2022 •

edited

Loading

oliviertassinari commented Feb 16, 2022 •

edited

Loading

mbrookes commented Feb 17, 2022 •

edited

Loading

oliviertassinari commented Feb 17, 2022 •

edited

Loading

mbrookes commented Feb 18, 2022 •

edited

Loading

oliviertassinari commented Feb 20, 2022 •

edited

Loading