Where the heck should documentation for integrations end-user usage be hosted/posted/maintained? Could each integration usage information for end-users not be documented in a web-wiki or similar? MQTT and Z-Wave are currently the only integrations that are (somewhat) documented here for HA: https…

Here https://community.home-assistant.io/c/community-guides/51 ?

Wiki’s cannot be release managed correctly, which is a requirement for our workflow right now. So that is not an option. As for Z-Wave & MQTT pages, those should not have been created. It is chaos to find the actual page on how to set up a controller for example (as Z-Wave is now all over the place…

[image] tom_l: Here https://community.home-assistant.io/c/community-guides/51 ? Those are just guides for specific things in the forum which only the original poster can maintain. I am suggestion to have a wiki or similar solution which allows anyone to edit the pages.

[image] frenck: Wiki’s cannot be release managed correctly, which is a requirement for our workflow right now. Are there not any wiki frameworks that can be release managed as in have versions/revisions of pages? I have not checked this myself.

[image] Gamester17: Are there not any wiki frameworks that can be release managed as in have versions/revisions of pages? this is not about revisions or versions, this about staging and merging. For example, there are over 100 pages pending for “a” release in the future. All of those the rele…

You can’t make everyone happy, so can’t you just ‘aim’ that docs only be for latest non-beta release? Sure, might never hit that goal but most of the time the majority of docs will not change its essense. The meaning will still be there, end-users using latest release can probably figure out small…

[image] Gamester17: You can’t make everyone happy, so can’t you just ‘aim’ that docs only be for latest non-beta release? That is exactly what you see right now. But who is going to do those 150+ edits when a new release is done? For all the contributions? Wiki’s have their advantages, howev…

Oh one more thing. Due to it being a normal GitHub process, we can force/guarantee a change in the codebase has a matching documentation change pending (so we prevent code changes that aren’t documented). This has been a big issue in the past (for which we currently still are bleeding a bit).

[image] frenck: Considering it all, hitting the edit button on the current website, adjusting the markdown and submit it for review, isn’t that different from editing a wiki page to adjust the Markdown. I would like to argue that GitHub editing is simply not convenient or frankly somewhat int…

WTH should integrations usage and their technology be documented?

Archive Month of "What the heck?!" (2020)

frenck (Franck Nijhof) August 21, 2020, 9:40am 5

That is already possible with the current documentation. Every page has an edit button at the top.

In case you want a step by step guide: