[WIP] Standards/Style Guide for Documentation of Home Assistant #3461
Conversation
|
some how some way, those writting the docs that know this stuff need to phrase it in a way that us noobs can understand so more people with lower skill levels have access to setting up a running system, vs talking to skilled linux users and admins https://readthedocs.org ever lookin to some thing like this, says it build docs as git is commited, dont use it from that side, yet know I spend alot of time there for other app that use it. |
|
One thing I've found as a new convert to HA is that I miss seeing simple things like what it will look like in the UI if I do something I know it would be tricky to keep UI changes upto date with each release. There is tooling available through selenium and image checkers that could spot ui changes between builds and flag that a change in the docs may be required if that could help. For instance in here there's not a single picture of how a light shows up in the ui, what happens when you click it to bring up the panel etc. |
|
I think we should add some style guide to Markdown in general. Also, add some more automated checks on PR's. A full build might be too heavy, but we could add a liquid and Markdown linter and maybe even a tool like Alex. |
|
Using the new config format is important, but beyond that I think the rules will cause more harm than good unless there is hound-like CI to alert on them. Imagine (I would assume a common) usecase of someone seeing a typo, a missing parameter, or a not-clear-enough explanation. They use the "edit this page" button and send a quick PR. Then a week later a reviewer asks them to fix their oxford comma. I would assume half of the people won't bother. |
|
How about having a template for the different parts of documentation? Just define some headings which most components share like:
In the different sections we could write down some rules from your list or some best practice approaches. (If you start a new component, this could help.) This is just a quick example and needs some work, but I think you get the idea. |
NOT READY TO MERGE
Description:
I have started a list of documentation standards/styling guide, and would love to open the topic up to everyone for discussion.
This document/section will be expanding/changing quite a bit over the coming weeks (and possibly months), as we make our way through each of the documentation pages. Unfortunately, each page needs to be updated manually and cannot be batch processed. However, this also gives the opportunity to address and fix any syntax errors, logic errors, etc that we come across.
Please keep in mind that right now this is just "my thoughts" dropped into a quick Markdown file. This is why I am sharing it with all of you, so that we can address the rules of documentation as a community moving forward.