README Rework

[ElectronicsArchiver]

[ 
 Please Check The **Preview** 
 ][Preview]

• Add Tags

  
  

• Choose A License

  Not necessarily for the firmware, but for the repository itself / documentation.

  Especially to avoid the disclaimer section being plastered in READMEs.

  In case you choose one of the following licenses I'll consider this PR to under said license.

  ⤷ https://choosealicense.com/licenses/

  
  

• Disable Unused Widgets:

  • Packages

  
  

• Disable Unused Tabs:

  • Actions

• Separated sections into topics

• General formatting / spacing

• Converted raw links into link references

• Added quicklinks

• Temporarily moved the disclaimer

• If you have any questions.

• In case you do not agree with some of the changes made in this PR,
  please first let me know about them, before disregarding it entirely so
  we can possibly find a middle ground and have it not go to waste.

[marcus-j-davies]

@ElectronicsArchiver,

Your issue links need updating. If you look at my PR, you will see the new links.

@jascoproducts have updated the templates ever so slightly, my PR addresses it for the read me, it looks as if your PR contains the wrong links, copy them from my PR and you should be current. 👍

[ElectronicsArchiver]

@marcus-j-davies

Sure, will do.

( Didn't wanna 'take your work'~ )

[marcus-j-davies]

Nah, my PR is just to correct the links. If you use the ones in my PR. Your golden.

Yours is a rework of the read me, mine isn't 😉

[jascoproducts]

@ElectronicsArchiver Thanks for all the great work! We'd like to exchange some ideas with you.

SECURITY.md and your formatting style looks great, but we have some specific requirements before we'd consider merging.

1. Please leave the disclaimer literature as it was. Our disclaimers throughout the repository are conspicuous by design. We have already reviewed this firmware project with our legal department and have decided to implement those as an alternative to choosing to defer to another software license.

2. Please remove the Topics folder and hotlinks for Identifying Your Product and Updating Firmware. We are actively considering ways to update the readme to make it more accessible, but we have decided that the literature, rather than be broken off into topics, should be contained within and accessible from the main README.md. We want to avoid requiring users to click and acknowledge separate links.

Let us know your thoughts and feel free to make changes for further review. Looking forward to working with you.

[ElectronicsArchiver]

 
 Preview 
 

Changes

• Adjusted as above requested

• Quicklinks still remain, but are linked to the local headlines

Consider

Please leave the disclaimer literature as it was. Our disclaimers throughout the repository are conspicuous by design. We have already reviewed this firmware project with our legal department and have decided to implement those as an alternative to choosing to defer to another software license.

Right, well you still might want to talk to your legal department to consider a license for the repository itself.

The disclaimer seems to solely protect you legally from misuse of the firmware and doesn't address the repo itself.

Repositories having multiple license / disclaimer / .. is nothing special, so it would be much appreciated if the repository - and thus the documentation - was under a normal license like the GPL flavors.

This wouldn't influence the disclaimer of course~.

[jascoproducts]

Thanks for the great work; looks fantastic. Merged your commits.

Thanks also for the info about licenses. Are there any specific problems you or other potential collaborators could foresee/currently are running into if we continue as-is without declaring a license? We're wanting to gain some more information before we bring others forward internally to discuss issuing one.

[ElectronicsArchiver]

The Problem

Thanks also for the info about licenses. Are there any specific problems you or other potential collaborators could foresee/currently are running into if we continue as-is without declaring a license? We're wanting to gain some more information before we bring others forward internally to discuss issuing one.

Well without a license for the repository, technically I couldn't even be sure if I was allowed to read / work on it.

This pullrequest as well is technically rather problematic since it was commited to a repository without a license.

Note

As I stated, I will accept my contribution to be under any of the default licenses if you choose to add one.

---

The following is non-specific information that you may or may not care about.

Sorry, I just couldn't stop writing~

Setting A Standard

Choosing a license also sets a standard, meaning if you wanted to change to another license, all contributors would have to agree to this change of license.

As we are only talking about a license for the repo and it's documentation, there usually wouldn't be any need to ever change the license in the first place.

Setting A Statement

Choosing to publish a work under an open source license, like a flavor of the GPL, tells people you are ready to work together to not only benefit yourself but to improve on things together.

In a present where proprietary is the norm for many companies, making something, anything, with a permissive license may be seen as a gesture of goodwill & progress.

Obscurity Is Not Security

To expand from the topic of licensing documentation to licensing to source code, one major benefit that comes with it, is the potential for improved security.

Hiding your problems never helps and it is only a matter of time before people that want to find them, will find them.

Publishing source code makes it easier for attackers to find what they are looking for, but it also allows people to point out and fix those same attack vectors.

It turns the table from a matter of time to can be mitigated.

More eyes on the code, more feedback and more fixes can massively improve a software security.

Maintainability

Just as a quick note for the last paragraph, what also improves with people being able to contribute is code maintainability.

There thankfully are some people that strongly care about writing code well, documenting things properly and overall making software more easily usable, not only from the side of the user but also the developer.

Stepping Stone

While one may have to swallow their pride to publish their sources and potentially be criticized about the way they developed whatever it is they created, doing so can:

• Open the path to a better relationship with the people that care about that project / product / ..

• Improve the user experience, security, maintainability

• Set a standard for peers to do similarly

[jascoproducts]

@ElectronicsArchiver Thanks for the super detailed info on the license. We are in the process of choosing one.

Would you be willing to make another button and section for Finding Your Firmware? We want to show users how to search for firmware using this method:

1.

2.

[ElectronicsArchiver]

Sure, do you have an example string for the search / found firmware you want to use?

[jascoproducts]

Let's do:

• "you can search for a Z-Wave number" = ZW4008
• "or a specific model number" = 46201

Does not have to be that exact wording in quotes but that's what we'd like to convey.