WTH should integrations usage and their technology be documented?

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

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://www.home-assistant.io/docs/

The documentations for those integrations are currently only hosted in a standard repository on GiHub:

https://github.com/home-assistant/home-assistant.io/blob/dbd5eabd1442669c795a432029d56754e1e0b788/source/docs/index.markdown

By usage information I mean for example, technology explanations, use case scenarios, device guides, best-practices, tips and troubleshooting issues with RF-range issues in different environments, etc. and not just basic installation setup. Similar to the existing Z-Wave docs at https://www.home-assistant.io/docs/z-wave/ which is not all on one page but instead have several sub-pages which each cover more in-depth details about specific areas.

Should we submit docs for other integrations not documented there, such as for example ZHA docs?

I know that the core team don’t wish us to flood integrations page with too much text about usage, like:

https://www.home-assistant.io/integrations/zha/

Personally I would prefer to edit/write on a web-based wiki instead of only keeping docs in a repository.

https://docs.github.com/en/github/building-a-strong-community/about-wikis

A tip is that GitHub wikis can also be maintained as source code via git just as any repository.

https://docs.github.com/en/github/building-a-strong-community/adding-or-editing-wiki-pages

So with that solution a wiki can also be maintained as source code on GitHub via git by developers too.

The main benefit with a wiki is that it makes it much easier for non-devs to contribute documentation.

2

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

3

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).

The current goal is to have a page per integration. Longer pages are not a problem, if provided an index. Which is being worked on as well.

4

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.

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:

6

Are there not any wiki frameworks that can be release managed as in have versions/revisions of pages?

I have not checked this myself.

7

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 release, is unkown, could be 0.115, or even 0.120.

There are also around a ~150 changes pending for the 0.115 release. Meanwhile, the current documentation is changed and adjusted daily (typos fixed, improvements in general, blogs, you name it. Anything that applies to 0.114 right now).

During a beta we actually have another copy running for the beta. That will receive beta fixes / adjustments and the updates from the current website as well. But not what is coming up in the next release after that.

So this is about branching and merging.

8

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 changes.

Z-Wave integration is problaly an uncommon exception because it is undergoing a complete re-write.

9

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, however, this is exactly the point where Wiki’s fail.

I don’t see how that is related to the z-wave documentation being a split mess around the website.

Recap:

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.

10

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).

11

I would like to argue that GitHub editing is simply not convenient or frankly somewhat intimidating and extremely not user-friendly to non-developers compared to the on-the-fly web-editing features in modern wiki frameworks such as for example MediaWiki.

Just editing a page on Wikipedia to compare will make anyone who is not a developer should see that:

https://en.wikipedia.org/wiki/Home_Assistant

Compare that wiki editing process to this process to edit docs files via GitHub:

I will be willing to bet a lot of money that Home Assistant would get loads of more people contributing to all of its documentation then you do today when solely relying on updates via pull requeststo GitHub/git.

It is a well-know “fact” that developers do not like to do end-user documentation, however, in my experience, many non-developers who cannot contribute code are willing to contribute to end-user documentation if the process of doing so is convenient (as in not complexed or cumbersome).

Wiki is designed to make it convenient to edit the text in web-documentation on-the-fly, pull requests via GitHub are not.

12

Oh don’t get me wrong, I totally agree, that editing a Wiki would be easier for a lot of people. It certainly has its place and strengths.

However, it has a couple of downsides, as mentioned before. Those things are important as well.
Lastly, a review process helps improving things as well and keeps stuff that are incorrect (and newly introduced), out. With a Wiki you’ll need a team of people going after that fact.

I really would never agree on the current documentation becoming a Wiki.

Yeah, developers hate docs in general. Hence we now can enforce that. The code change made by a developer cannot be merged without documentation.

13

Yes this is the very same process that makes it not convenient at all for non-developers to edit docs:

14

Not so. Read the category description. It functions as a wiki. Anyone can edit posts.