Keep track of brand guidelines/presskits/etc. explicitly

[ericcornelissen]

Issue: Closes #755

Description

This is a candidate implementation of the feature proposed in #755. It adds an option field to the data file called guidelines which is used to link to the brand guidelines/presskit/similar if they exists. I also added a couple of guidelines as examples.

Note that this data will not be added to the NodeJS package!

This approach feels a bit awkward because in many cases the source and guidelines will be the same exact URL. However, for the website redesign (#980) I think it would be nice if we could link to the guidelines explicitly (if they exist), as seen on the BrandColors webpage:

An alternative approach could be to make one of source or guidelines required? However, the existing data would need to be updated for that, which is quite a lot of work 😅

[PeterShaggyNoble]

My suggestion would be to keep the source entry as-is and continue using it as we currently do and then add an optional website/homepage entry.

[ericcornelissen]

My suggestion would be to keep the source entry as-is and continue using it as we currently do and then add an optional website/homepage entry.

Do you mean website/homepage instead of guidelines @PeterShaggyNoble? If so, as discussed in #2260, that seems unnecessary to me as part of being "popular enough" should be that your website is easy to find using a search engine.

My motivation for guidelines specifically is that it may explain how the brand wishes you use the logo (and colour and name and more). Again, it may be the same as source for some/many icons. But take for example "Corona Engine": the SVG is taken from the homepage while they also have brand guidelines.

[PeterShaggyNoble]

that seems unnecessary to me as part of being "popular enough" should be that your website is easy to find using a search engine.

👍 A fair point

My motivation for guidelines specifically is that it may explain how the brand wishes you use the logo

Ah, now I get it. In that case, then, I agree with this as-is. We just need to make sure it's clear enough that the new entry should only be included when the URL for the brand guidelines differs from the source URL so we'll need a better example (e.g., Corona Engine) for CONTRIBUTING.md.

[ericcornelissen]

Ah, now I get it. In that case, then, I agree with this as-is. We just need to make sure it's clear enough that the new entry should only be included when the URL for the brand guidelines differs from the source URL so we'll need a better example (e.g., Corona Engine) for CONTRIBUTING.md.

Not 100% sure if we're on the same page yet. The example in CONTRIBUTING.md is also correct. Agreed?

Either way, I'm not against updating the example to Corona Engine. I'm not sure what serves as a better example: one where the source and guidelines values is the same or one where they're different 🤔

[PeterShaggyNoble]

My suggestion is that we only use the guidelines if they differ from the source so as to avoid duplication.

[ericcornelissen]

My suggestion is that we only use the guidelines if they differ from the source so as to avoid duplication.

Let me ask you something first. Do you agree that it would be nice if we could link to the brand guidelines in on the website? If not: sure, that works just fine.

If so, how would you reckon we achieve that if we only use the guidelines fild if it differs from the source field? There are a couple of scenarios with these two fields:

1. We have a source for the SVG, but no proper guidelines
   in this case I think we should not provide any link on the website.
2. We have a source for the SVG and a different URL for the guidelines
   In this case I think we should provide a link to the guidelines on the website.
3. We have a source for the SVG and the same URL for the guidelines
   In this case I think we should provide a link to the guidelines on the website.

If you agree with the above, then how do you distinguish 1 from 3 if guidelines is only specified when its different from source. Again, I agree that the duplication is a bit ugly but if we want to display this information on the website I think it's the best way.

Alternatively, we could allow guidelines to be both a string and a boolean. If it's a string it must be a URL for the guidelines. If it is a boolean and true it means the source URL links to the brand guidelines (and false or the field being omitted means there are no brand guidelines). This avoid the duplication, but in my opinion is unnecessarily complicated. Also, I think this approach is more likely to go wrong in the (unlikely) event that the source URL changes from brand guidelines to something that isn't brand guidelines.

[PeterShaggyNoble]

Ah, OK, I get you now; I was coming at it from a completely different perspective. Although not ideal, the potential duplication between the two is definitely more straightforward than the Boolean option.

One thing I'd still suggest for the new website is that if source=guidelines then we just display one link with the text "Source & brand guidelines" to avoid having two links that go to the same place.

[ericcornelissen]

Ah, OK, I get you now; I was coming at it from a completely different perspective. Although not ideal, the potential duplication between the two is definitely more straightforward than the Boolean option.

After your last comment I realized I should have been more specific about my idea behind adding the field 😃

One thing I'd still suggest for the new website is that if source=guidelines then we just display one link with the text "Source & brand guidelines" to avoid having two links that go to the same place.

That should be doable when we implement this on the website 👍 Just FYI, I had not yet thought of having a link to the Source as well but that could certainly be useful!

[ericcornelissen]

Any input regarding this from newer @simple-icons/maintainers? (it would be cool if I could include these links in the redesign)

[adamrusted]

I imagine 9/10 times if there are brand guidelines, that is where we've extracted the logo from in the first place - though I know (in cases such as some of these Google icons) that may not always be the case.

In an ideal world, I'd say we should be showing source as where we found the SVG, brand_url as a direct link to the brand's homepage, if different to the source (though I take the point on about these being easy enough to just Google), and guidelines as optional if such a page is present on the brand's website - to easily allow our users to check rules regarding specific logos. It's a case of how much we want to bloat the JSON file, and how much extra work we want to do in order to get the file to match the new spec!

[ericcornelissen]

I will state again that I would be strongly against adding a brand_url field for the reason you point out as well, but even so that discussion shouldn't stop this PR from being merged.

Also, just to clarify, I don't think we as maintainers need to take any action in adding brand guidelines for existing brands beyond those we are interested in ourselves. Contributors are welcome to do the same for existing brands they're interested in. The only thing we ask now is of new contributions and updates to existing icons to consider this field.

As for the duplication, I guess that is the main point of discussion here (beyond whether we want this to begin with).

[fbernhart]

I totally agree with @adamrusted.

Actually, how much would "bloating up the JSON file" really be a problem?

Concerning the different attributes:
In my opinion we already have "not quite easy" contribution guidelines with already quite some rules. And I would really like to avoid making it more complicated, if not really necessary. So that the barrier for new contributers is kept low.

And in my opinion adding new rules like "only add a guidelines attribute if it's different from the source" are making it more difficult to contribute for people that are new to Simple Icons.

How about just always adding a source and guidelines attribute? If both, the SVG and the brand guidelines, can be found on the same page, it will be the same URL twice.

If there are no brand guidelines, we could just add a NaN/None value or an empty string (not sure what the JSON equivalent is).

E.g.
Different URLs:
source: "facebook.com/logo.svg"
guidelines: "facebook.com/brand"

No brand guidelines:
source: "microsoft.com/logo.svg"
guidelines: None

Source & guidelines are the same:
source: "twitter.com/media-kit.zip"
guidelines: "twitter.com/media-kit.zip"

[adamrusted]

If there are no brand guidelines, we could just add a NaN/None value or an empty string (not sure what the JSON equivalent is).

Looking at the JSON linter, there just wouldn't be a value, and on the front-end it's just a simple check of whether the data exists before displaying it.

I think you've perfectly captured what I was trying to say above with the two different links, and fully get @ericcornelissen's point about not wanting to include links to just homepages etc.

At a cursory glance, the PR covers that perfectly - but will look at it again when back in front of my PC tomorrow.

[fbernhart]

To not mix up vocabulary:

By guidelines I mean something that will point to the company's brand page / style guidelines. I'm mostly interested in the place where they mention "Main brand color: #5201FC". As I find it hard (especially reviewing PRs and outdated icons) to find out if the color has changed and why a certain color was used in the first place.

So mostly this will benefit us maintainers and maybe not the average user.

I don't think we necessary need to include an attribute that will link to the "Do's and don'ts" of using a specific icon.

[ericcornelissen]

That is exactly what the intention of this PR s @fbernhart. It should benefit the average user to the extend that they should care about the guidelines of the brand, though admittedly many will not. And indeed, the JSON equivalent of None/NaN/empty string is to just leave the value out, this is captured by making the field not-required in the JSON scheme (.jsonlintschema).

I don't think we necessary need to include an attribute that will link to the "Do's and don'ts" of using a specific icon.

I expect this to usually be the same page/set of pages, but of course that depends the brand. I think this should really be decided on a case-by-case basis. Though it is useful for reviews to have this page, this page can (and should) be linked in the PR description, whereas the JSON data is ultimately for users of Simple Icons.

In this regard, if you ever wonder why the original color in the JSON data is as it is, check out the PRs for that brand!

[adamrusted]

Looks good to me!
Is it worth updating the Issue template for new / outdated icons, to request the second link?

[ericcornelissen]

Looks good to me!
Is it worth updating the Issue template for new / outdated icons, to request the second link?

I'd say this falls under the part:

**Official resources for icon and color:**
  <!-- for example media kits, brand guidelines, SVG files, etc. -->

But if you have suggestions for making it more clear/explicit, I'm all ears 🙂

[adamrusted]

But if you have suggestions for making it more clear/explicit, I'm all ears 🙂

You're right. I thought our Issue template asked for a link to the SVG separately, it doesn't 🙃

[runxel]

I really like to see this one merged.
Is there anything (besides the obvious conflict) we need to consider before merging?

[ericcornelissen]

I really like to see this one merged.

I'll fix these momentarily 🙂

Is there anything (besides the obvious conflict) we need to consider before merging?

From my point of view, no unless someone doesn't want this (e.g because of duplication). It's a non-required request for adding a link to the brand guidelines.

As for size concerns, the only file whose size will be significantly increased is the generated index.js file for the NPM package, as it will contain all of these URLs. But if a package user is concerned about size they should probably not be using index.js to being with...

[adamrusted]

Merging as only difference is addition of 'guidelines' data. Thanks for your work on this @ericcornelissen 💯

[ericcornelissen]

Cool, than I can look into integrating this into the redesign (#980) as well! 😄

[ericcornelissen]

The redesigned website now provides a link to the guidelines (if available), see e.g. the Corona Engine 🎉