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.
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.
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.
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
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.
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.
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.
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.
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.
I’ve got to say it, that comes across as really welcoming! If you’re new and don’t get something then go away and use something else. Don’t bother US with questions that WE know the answers to!
That’s your interpretation but I said none of those things. That was your very first post and you chose to misinterpret and twist my words.
This software, in its current form, is not a consumer-level product. Anyone thinking otherwise is deluding themselves.
Its documentation reflects the people using it and, in my opinion, it’s not likely to change to suit a different audience anytime soon. That’s not to say it will never change. Eventually it will because the goal is to create a consumer-friendly product. However, based on my experience with Home Assistant over the past 2 years, I would advise not to expect dramatic changes to its documentation ASAP.
I’ve already stated that I like home automation more than Home Assistant. I want other people to enjoy home automation as well. That’s why I suggested that if they find it difficult to comprehend Home Assistant’s documentation they should consider exploring other home automation software that may prove to be a better fit. Why suffer? Pick something you enjoy to learn and use.
I encourage you to check my profile. You’ll see that I frequently answer people’s questions.
It was an observation. The vast majority of first posts are questions about configuring Home Assistant. Your first post was to react to an opinion I never stated.
Should any of your future posts be about configuring Home Assistant, you’ll see that I and many others are indeed welcoming. When I started 2 years ago, there were about 30K members and now there are over 70K. Clearly, new users continue to be drawn to, and welcomed by, this community. I forsee that trend continuing unabated.
You were not alone. As active member of this community one should rather encourage to stay with the project and not advise to check on other either equally complicated or inferior projects. You are already helping so much. But a lot of threads in this forum could be avoided by just making better step-by-step tutorials.
To sum it up. Like Frenck said to me: Talk is cheap. Let‘s overhaul the Docs!
