Doc readability improvements #6568
Conversation
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
| @@ -22,6 +22,9 @@ Each of these two main folders contain domain folders. Each domain folder is | |||
| named to the integration `domain` and must match the domain set in the | |||
| integration `manifest.json` file. | |||
|
|
|||
| A third main folder `core_brands` is not updated by integration creators. This is only updated by core Home Assistant maintainers. | |||
There was a problem hiding this comment.
This isn't correct, please remove this.
There was a problem hiding this comment.
I was hoping you'd be more helpful as a reviewer.
What is the purpose of the folder core_brands? Its unexplained presence begs the question of its purpose.
| Whilst it is possible to have both in Home Assistant, a warning is signalled on the Integration page for the custom integration: `Custom integration that replaces a core component` / | ||
| It will not be possible to publish such a custom integration via HACS since valid branding repository will not be possible. |
There was a problem hiding this comment.
This isn't relevant for this repository. Let's remove this.
There was a problem hiding this comment.
As I said, this one line would have clarified my confusion at this point.
I'm sure I'm not the only one learning Home Assistant reading these docs expecting clarity.
Why do you want them to be less informative than they could be?
|
|
||
| It is possible for a custom integration and a core integration to collide on | ||
| a `domain` name level. In these cases, the core integration domain get | ||
| preference. | ||
| their `domain` name. In these cases, the CI will fail. \ |
There was a problem hiding this comment.
CI will fail in many more cases, I'm not sure why we need to call that out. The goal of the CI is checking if requirements are met, we should describe it from that perspective.
There was a problem hiding this comment.
These are your words you take exception to.
Again, lack of clarity seems to be your goal here.
| a `domain` name level. In these cases, the core integration domain get | ||
| preference. | ||
| their `domain` name. In these cases, the CI will fail. \ | ||
| To resolve domain name collision, a pull request to this repository linked to the core integration that moves the domain from custom to core in this repository. |
There was a problem hiding this comment.
This is describing how to solve a problem, not a requirement.
There was a problem hiding this comment.
Knowing how to meet the requirement would be helpful when the situation arises.
Again with the being less helpful than it could be.
I'm starting to see why the docs in general are in such poor shape.
|
regret trying to improve docs - clearly the inner circle don't want outsiders helping. |
Proposed change
Type of change
Python wheels repository
Additional information
Checklist
icon.png)icon@2x.png)logo.png)logo@2x.png)