Not true. When I click on history there are changes that have nothing to do with the yaml doc.
A commit can change multiple files, iif you open one of them, it shows you the change to that document (and others if they are)
look at the links Lueeus gave about how github works
I don’t know if it’s necessary to pause a release cycle just for this, as this problem is honestly something the community is capable of handling entirely on their own. Much of the issues with the docs I would classify as low-hanging fruit; things that take very little effort and time to fix.
But I support your general idea. Just like we have the “month of WTH” going on right now, it would be nice to have an annual “month of Docs” or something. Teach people how to contribute to the docs, come up with a list of focus areas and some type of “style guidelines” so that everyone is on the same page, and then work together to fix all the issues.
In fact, coming up in October is something called “Hacktoberfest” which encourages people to get started contributing to open source projects by rewarding them with a free t-shirt and stickers after 4 pull requests. So if anyone wants to help out, that could be a little bit of extra motivation 
5 Likes
Great idea!! An effort like this, especially the parts about helping beginners learn the ropes and prioritizing their efforts, might finally get some momentum in this area.
1 Like
This. Is what’s missing.
1 Like
Have you seen this?
2 Likes
Bill- I also come from a long history of controlled documents. I remember the gnashing of (engineer’s) teeth when the company decided we had to be ISO-9000 compliant.
But, I really don’t see a need for document control of the documentation. Most people don’t run old versions of HA. If they are, then they probably installed HA three years ago and never wrote another line of YAML; and they would never pull an older version of the docs anyway. The docs are for people running the latest version of HA. Period. No one will ever update an older version of the docs. Ever.
3 Likes
I don’t run old versions. Would I do try are still supported integrations. They are new to me and I just want to make sure the documentation is still applicable.
You are completely missing the point. Totally.
So, the documentation is written in an obscure markup language named Markdown. Markdown is a Perl script running on a Linux Server using a front-end called Movable Type. Or SmartyPants. Or Bloxom. Or BBEdit.
Sure, anyone who really wants to help with the documentation just has to learn Markdown, run it on a linux server and use Movable Type. Easy.
As Sean said- and I highlighted- Teach people how to contribute to the docs.
Not really that obscure, and it has to be written in something - what do you suggest?
1 Like
Wow…
Good luck!
I’m out
5 Likes
Whoah.
As an old timer I would like to caution against hasty typing. It is not required to piss people off so they regret their initial contribution.
I am a very much beginner HA - i have no linux knowledge - I tinker around with small time electronic circuits and once thought spending 3 hours copying a basic program from a printed page onto a TI994A so that I can have a very pixelated game of rebound tennis was the bees knees in computing.
I try to use the docs but struggle at times with the level of assumed knowledge.
Most of my HA setup has come from watching people like BURNS, DRZZZ’s, JUAN and others. Their concise explanations with graphic content are invaluable.
This is what I see the future docs being - a form of multi media approach to learning.
Mind you with the pace of AI development the docs may become a relic we don’t need to worry too much about as some bright spark like Ludeeus or Frenck will put an integration in that we just speak with and it does the back end setup for us.
Go HA
2 Likes
Yep, it is easy.
I managed to learn how to use MD in about 30mins playing about in this. Stop being doltish.
2 Likes
I’ve got you beat. I wrote a Yahtzee program in TI 99 assembler language once. The architecture of that hardware was generations ahead of its time.
My point is, I tend to agree that there’s a level of assumed knowledge here that isn’t universally shared. Beside the TI 99, I’ve coded on everything from a S-100 bus 8080-based computer I built myself to IBM mainframes to every version of DOS and Windows Microsoft ever released. There was also a fair amount of custom hardware that nobody’s ever heard of in between. But because I’m not a UNIX guru, I’ve been publicly scoffed at here.
Seem’s like you know a lot about this. Why don’t you make a community guide?
2 Likes
Personally, I like the Wiki format, but there’s no way I would support a change to the documentation platform.
But it does seem to be onerous to pull a copy of the entire documentation, try to find the correct markdown file to change, then push the entire documentation back to the Git.
I am in the process of remodeling a few rooms in my house- but when that settles down, maybe I will write a documentation of the documentation. recording all my missteps along the way. It couldn’t possibly be from the perspective of anyone less familiar with the process (except that I already have a Git account).
You don’t have to do that… you can go on github and edit the page directly. Make a change and request a pr. It takes 2 minutes. I’ve done it from my work computer in the past which does not have a full copy of the documentation.
3 Likes
The steps to editing documentation on GitHub is almost exactly like a Wiki. You’re pressing edit, rewriting whatever text you want, previewing those changes, writing a brief edit message explaining the reasoning for your change, and then submitting.
Here’s one that is beginner friendly.
- Go to this page: https://www.home-assistant.io/docs/configuration/devices/ and click the “Edit this page on GitHub” link at the very top (right next to the page title).
- Now you’ll see the page on GitHub. Look for the pencil icon and click it to edit the page.
- Go to line 66 and highlight this text:
Each group consists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the Set State page in the Developer Tools (<img src='/images/screenshots/developer-tool-states-icon.png' alt='service developer tool icon' class="no-shadow" height="38" />). - Replace the text with this (copy and paste):
Each group consists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the “States” page in the Developer Tools. - Optional - you can press the Preview tab at the top to switch between editing mode and preview mode. It’s just like a Wiki where red highlighted text means removal and green highlighted text means addition.
- In the “Propose changes” section description box write “Removed outdated reference to developer tools icon” and then press the green “Propose changes” button
- Press the green “Create pull request” button. No need to do anything else on this page.
- In the issue template add an X inside the checkbox for “Adjusted missing or incorrect information in the current documentation”
- Click the green “Submit Pull Request” button… Done, congrats!
I encourage everyone to try that. You don’t have to actually do the final step 9 (submitting) if you don’t want, but go through all the other steps to familiarize yourself with the process. Run a stopwatch and you’ll see that it’s truly just 2 mins and significantly easier than you were imagining.
Those steps are completely from your web browser. You don’t need to download the entire repository, you don’t need to be an expert in Markdown. You don’t need to have command line knowledge. You don’t need to download an app. It’s extremely similar to a standard Wiki edit, everybody can help with documentation.
9 Likes
Here’s an idea: Is there any place we could post detailed “how to” instructions?
I’ve found it very helpful when someone posts an answer to a specific question that takes me step-by-step through the process, start to finish. It’s even more helpful when I don’t have to stop and do a lot of research like “what did he/she mean by THAT??” along the way.
I’ve found myself doing that sort of thing for my own use, so I don’t forget what I did. I’ve posted one or two of them, and I’m always getting “likes” for those posts. So I’m not the only one.
Granted, not everyone is doing exactly what I want to do, but often it’s close enough that I can follow the steps and tweak things along the way.
Ideally, these would be fairly large documents, with not only detailed steps, but also screen shots and snippets of things like configuration.yaml. These are very different from reference documents, which should be more concise and cover all possible options.
Or maybe there’s already something like that I haven’t found yet.
Yes, the Community Guides section!
6 Likes