Proposal for clarification about links to be included for icon source data

[gizmecano]

Description

After learning about the possibility of adding optional data, I have recently decided to update some of my previous contributions. In two cases, changes were requested by maintainers: #6323 (review) by @service-paradis and #6320 (review) by @jorgeamadosoria.

In both cases, it was because the modified source link pointed toward a file instead of a page.

Currently, the source guidelines seem not be explicit enough to indicate that the source link should be a page and not a file (with a notable exception about GitHub repositories).

This pull request is a proposal for clarification about links to be included for icon source data, adapted from the comment posted by @service-paradis (mentioned above):

In both cases above (Branding page and Company website), pay attention to link to a page that includes file instead of link to direct files. This way, if the file name or path changes, the link will still be working.

---

To conclude, regarding this question, at least two sources indicated in the data file are currently pointing to files and not pages: #5497 and #1000 (which could be updated according to #6235). As these are indeed "Branding page" or "Company Website" types, they probably have to be corrected in the future according to this point.

[ericcornelissen]

While I'm not necessarily against including a note like this (after all, the past gives us proof the current guidelines are insufficient) I can't help but wonder why the current guidelines are sufficient. For example, take the string for Branding page: "For an SVG from a branding page the source URL should simply link to the branding page." To me, that can only mean one thing, namely that you should link to the branding page.

with a notable exception about GitHub repositories

Just to clarify here, in the case of GitHub we can be nearly 100% certain (provided it's a default branch) the file will remain available there. Of course, this also goes for other git hosting websites.

To conclude, regarding this question, at least two sources indicated in the data file are currently pointing to files and not pages: #5497 and #1000 (which could be updated according to #6235). As these are indeed "Branding page" or "Company Website" types, they probably have to be corrected in the future according to this point.

Thanks for bringing this up. #1000 definitely happened before our current guidelines so that's no surprise. As for #5497, sometimes these things just slip through the review process. But yes, ideally both of these are fixed.

[jorgeamadosoria]

In both cases above (Branding page and Company website), pay attention to link to a page that includes file instead of link to direct files. This way, if the file name or path changes, the link will still be working.

I think that including the excerpt would be redundant, but in the light of this being an issue that shows up fairly frequently, maybe we should add it just to spell it out for future contributors.

I'm ok adding it if we can get a consensus.
A text similar to the one @gizmecano proposes (or that same text) could work just fine:

In both cases above (Branding page and Company website), pay attention to link to a page that includes file instead of link to direct files. This way, if the file name or path changes, the link will still be working.

Thoughts, @simple-icons/maintainers ?

[ericcornelissen]

My thoughts exactly @jorgeamadosoria, but before we merge this I would like to explore if we cannot just improve the existing text.

As for the text, I think there are a couple of improvements for grammar, brevity, and correctness.

In both cases above (Branding page and Company website), pay attention to link to a page that includes the source image instead of the source image itself. This is because such a link is less likely to become invalid than a link to the image itself.

[sachinraja]

A few things that (I think) would be better:
For Branding page and Company website, link to a page that includes the source image and not the source image itself. Such a link is less likely to become invalid.

[jorgeamadosoria]

My thoughts exactly @jorgeamadosoria, but before we merge this I would like to explore if we cannot just improve the existing text.

As for the text, I think there are a couple of improvements for grammar, brevity, and correctness.

In both cases above (Branding page and Company website), pay attention to link to a page that includes the source image instead of the source image itself. This is because such a link is less likely to become invalid than a link to the image itself.

I' ok with your version or @sachinraja 's. They spell the meaning rather nicely.

[gizmecano]

I see that this little detail has given rise to some thoughts.

Now the question is: which revision proposed by a member (@ericcornelissen and @sachinraja) should be chosen to correct the addition made by the pull request? Do any of the other maintainers see another possible variation for this phrase?

(As I am not a native English speaker, I trust you to correct this appropriately... 😉)

[ericcornelissen]

I would prefer @sachinraja's version as it's simpler and more straightforward than mine.

That said, @gizmecano, do you have any opinion regarding my earlier comment: why is the existing text insufficient in your eyes?

[gizmecano]

That said, @gizmecano, do you have any opinion regarding my earlier comment: why is the existing text insufficient in your eyes?

It is often difficult to explain the reasons for not understanding a piece of text...

🤔

In my case, I suppose that these "page" rather than "file" references (in Branding page and Company website sections) turned out to be too little explicit, especially in comparison with the two sections devoted to GitHub and Wikipedia/Wikimedia, which are depicted with more precise details...

[sachinraja]

Hey, don't worry about keeping this updated. A maintainer will push an update or ask you to push an update to the branch before merging.

[ericcornelissen]

In my case, I suppose that these "page" rather than "file" references (in Branding page and Company website sections) turned out to be too little explicit, especially in comparison with the two sections devoted to GitHub and Wikipedia/Wikimedia, which are depicted with more precise details...

Okay, in that case I would personally suggest to make the individual points more explicit, e.g.:

- **Branding page**: For an SVG from a branding page the source URL should link to the branding page and not the image, PDF, or archive (such as `.zip`) file.
- **Company website**: If the SVG is found on the company website (but there is no branding page) the source URL should link to a common page, such as the home page or about page, that includes the source image and not the image file itself.

Yes, this is a bit redundant. However, it prevents back referencing from a point that the reader my never reach (e.g. if I found a branding page, I'm not going to read past that bullet). Not to mention that the current formatting suggests, visually, that the added paragraph belongs to the Company website bullet, which conflicts with the paragraph's content. This can be seen clearly from GitHub's visual diff:

---

---

[gizmecano]

Hey, don't worry about keeping this updated.

Sorry for the inconvenience: I've made this only for updating my local branch. 😕

[gizmecano]

Okay, in that case I would personally suggest to make the individual points more explicit (...)

So, if I understand correctly, you are proposing to also alter texts of both preceding sections. I have included these amendments in a new pull request: 2a3d3e2.

But would it be in addition to the additional paragraph (as I think I understood) or in replacement of this paragraph (because I have doubts about my understanding)?

As you wrote redundant, I supposed the first hypothesis is the right one, but let me know if you want I update the pull request by removing the added block.

[ericcornelissen]

My suggestion was to only update the existing sentences, not add the new sentence.

Sorry for the inconvenience: I've made this only for updating my local branch

If it can be avoided that is ideal. Such commits may trigger a notification for everyone subscribed to this Pull Request, which is a bit pointless if nothing really changed.

[ericcornelissen]

I would be happy to merge this as is, what do you think @sachinraja & @jorgeamadosoria?

[sachinraja]

Looks good to me

[jorgeamadosoria]

I would be happy to merge this as is, what do you think @sachinraja & @jorgeamadosoria?

I think the text makes the issue clearer. LGTM

[ericcornelissen]

Thanks @gizmecano for improving the Contributing Guidelines! 🎉