search

raspberrypi / hats

BSD 3-Clause "New" or "Revised" License
661 stars 144 forks source link

Design Guide Improvement #69

Closed StevenGann closed 1 year ago

StevenGann commented 4 years ago

Cleaned up the design guide a little to clarify a some of the language, be a bit more brand neutral, and list some alternative EEPROMs that are compatible with the specifications.

JamesH65 commented 4 years ago

@jimbojr Are you the HAT docs go to guy?

StevenGann commented 3 years ago

I am a Microchip employee and it is clearly declared on my profile, but I don't think I need to wear a special hat or blow a horn because of it whenever I do something in my free time. I've clearly stated my affiliations and it's plainly visible that my edits are brand-neutral and improve representation while the original was highly biased and made false claims to promote that bias. My objective is to make the documentation factually correct, less misleading, and easier to understand for new folks who might not be familiar with the different varieties of EEPROMs.

JamesH65 commented 3 years ago

On the whole, the documentation aim is to REDUCE the amount of recommendations we make as these always come back to haunt at some point. To that end I'd suggest removing any reference to third party products at all. i.e. remote the OnSemi recommendation, and the table. That way we are not targeted with claims of favouritism from any direction.

rgetz commented 3 years ago

On the whole, the documentation aim is to REDUCE the amount of recommendations we make as these always come back to haunt at some point.

As a developer - I like it when validated/verified part numbers are shared in the doc. It indicates how what (if any) has been tested and validated. A list of what is known to work is better than a spec...

JamesH65 commented 3 years ago

But as you can see, a third party wants to add their chip, which WE haven't tested. So what should we do? We don't do validation as a matter of course on stuff we don't use.

rgetz commented 3 years ago

That's easy - don't add it.

Or clearly state that during your validation/verification/release process - the ones noted (*) are tested, and the others aren't, but have been reported to work by others.

That way developers know there are alternatives, but you don't get stuck answering questions on hardware you don't have.