Also, in the Getting Started section it would probably be a good idea to offer up a NUC install as well as the RPi. I know there’s a decent cost hike but if it’s mentioned that you get a much faster and capable system with basically the exact same install method (HA OS), I think a lot of people would go for it. (no SD card dramas, ability to record multiple HD CCTV streams etc.)
I think all references to NUC should be expunged. Any x86_64 computer will work. We are not an advertising agency for Intel.
And yes I know there is a version of HA OS for the NUC and identical chipsets.
1 Like
Yeah true, if the install works on other machines then sure. I’m not up to speed with what hardware the ‘NUC’ install will work on
We have a glossary that is perfect for explanation of entity_id, domain, etc… it’s extremely out of date.
It’s even the first thing mentioned in the sidebar
EDIT: It’s SO out of date it mentions COMPONENT, not INTEGRATION!
2 Likes
Thank you for starting this valuable discussion.
While it has been discussed before, your polite, patient and helpful tone has made this one of the more productive threads on this subject.
I, too am willing to help with this. I was totally new to Python and barely exposed to UNIX when I came to HA, although I spent a career in IT, including lots of coding but also customer support.
I’d like to move beyond the defensive, dismissive, condescending or holier-than-though attitudes that this discussion usually brings. Let’s just agree that beginners don’t talk the same language as developers, and leave personal attacks out of the discussion.
Maybe we can assemble a team of like-minded individuals, who understand the pain of being a beginner, and have the time and/or motivation to do something about it.
Where do we begin? I have some ideas. Maybe do a step-by-step “sample” implementation. But then we need some way to keep up with all the changes. It seems some part of the documentation is made obsolete by every update. We also need a central repository. Github is a bit of a labyrinth for beginners.
2 Likes
Problem with the documentation is that its in a constant change at the moment, the requirement of both the devs and the community is massive
Yes everyone agree it could be better , but it requires everyone to get their hands dirty. The central repository is github, can it be made easier to submit, i cant say
Maybe as i think i read earlier in the thread, somebody submits a post here on the doco, then peer reviewed then someone who is familiar with github can submit a PR?
The other issue is that those who are in charge of approving/rejecting the pr need not to be dismissive of any updates people want to include. if the end result ensures the documentation is correct, can accommodate beginners and advanced users then all the better in my book.
1 Like
Problem is sean thos who look after the documentation stay hidden on the doco channel in discord, They need to come here and discuss with the community to get feedback/input to make the documentation better. This one area where the community can really help so engaging with them will be a positive
Also the process for submission has to be easier. look att this page from a first time trying to submit a edit or something new. Documentation | Home Assistant Developer Docs
they would be put off straight away
3 Likes
I’ll help.
I have quite a lot of notes I made while coming up to speed in HA.
I’ve been there. My background is engineering and one of my early jobs was converting engineering notes into a technical manual for consumers. So, I guess you could say that I am bi-lingual?
There’s Developers channels, how about a Documentation channel?
Perhaps there could be a separate Documentation discussion forum by invitation only? If we try to discuss the documentation in the general forums, you wind up with thousands of irrelevant inputs.
I was going to suggest something like this.
A separate forum section where changes to the docs can be suggested, made, reviewed and then passed to someone who can (and is prepared to) make the changes in GitHub if the original author can’t.
I’ve made few changes to the docs and it is quite daunting if like me you don’t know how GitHub works. Also if the change isn’t accepted straightaway it does make you feel a bit like a fish out of water trying to understand what is required of you to get it passed.
And then this…
…definitely this.
If ever there was something ‘The Community’ could help with, it is documentation. Any user can help there irrespective of technical knowledge. And by ‘help’ I mean at the very least flag specific deficiencies because even that would be a start.
And (cue the controversial bit), I do feel some of the blame for some of the ‘poor’ docs has to lay squarely at the feet of the those ‘at the top’. The glossary for example should never have been allowed to get out of date. And yes, it may hamper and slow development but surely part of the acceptance process for changes should at the very least include a question about whether the docs (might) need updating even if the onus isn’t on the developer to do it? More rigorous change management would be good but I can see there would be issues with that and it is probably unrealistic at this stage but at least if it were flagged as needing work someone else might be more likely to notice and decide to do it.
And just to finish, I used to hate the docs. I found them completely unreadable, undecipherable and with no clear structure to navigate through them for a progressive education of HA. Now though I think they are ok, I can usually find what I’m looking for. More evidence perhaps that they are only really suitable for those who already know how HA works and just want to look up some details?
1 Like
exactly. And in some cases I still do.
There are times when i know for a fact that there is a documentation page I had seen before explaining something, and, even now, I still have trouble finding those pages when I go looking. The doc structure kind of sucks for being able to actually find what you’re looking for.
3 Likes
My issue is when I try something new I have no idea if the documents are still applicable. I have asked for at the very least to show a document date and what’s version of HA it is valid for. I understand programmers want to program and documentation is far behind in importance to them, but there are enough people in the community willing to help if documentation becomes a priority.
6 Likes
Generally speaking (and a few things have fallen through the cracks - usually pages that aren’t linked from anywhere and so “lost” to all but Google) the docs apply to the current version of HA. Some will mention older versions, but if you’re not running the latest release you run the risk of the docs being invalid.
I’d recommend you add your suggestion there to a WTH - I’d vote for it.
1 Like
Two Thumbs up from me !
AND that way you could search for docs either older than (say) 6 months to check still valid or search on the HA version number and update that, again if still valid.
I offered my help in the past as I have a lot of experience being an EE, and former owner of an AS9100 aerospace power company. I understand document control quality standards, etc. and the importance of them. I was told that it was too hard and too time consuming to keep track of it an it appeared that the developers were not interested. The software gets better on each release, but the documentation still lags far behind. I still struggle when trying new integrations (new to me) in getting it to work by just following the documentation. Thankfully this community is willing to offer help so that I understand how to get the integration working.
Again with all the different options, HA is not for people that are not willing to put in the time. There is a big learning curve and I’m sure many people get discouraged before they see useful results. Thankfully I have enjoyed learning how to use it and find it the best option for automating my home.
It is an open-source project, not an aerospace company. The cool thing is, you can just go and contribute. Looking forward to your PRs!
?? There’s a Docs channel?
I understand this, but you were the person that told me that documents could not have revisions and dates. I have never seen a successful company not have a documentation control system. I am not looking to argue with you about the importance of this. I appreciate all the hard work you and others do. I just tried to point out to you the importance of it.
2 Likes
No, I told you the Home Assistant documentation is currently not able to handle that (technically). Besides, revisions is not solving the general content problem.
As you are constantly bringing up that one thing, I’m sorry to hear you are not willing to accept that.
Nevertheless, tons of other things to do.
We have that?
The entire documentation is hosted on GitHub, which includes source/version control.
If we knew the process or procedure.
Yes, the entire documentation is on github. In fact I saw that Frenk made a change request just an hour ago.
There are many users who would like to contribute to the documentation if we just knew how. The format of home-assistant/ home-assistant.io is unlike anything I have ever seen. Is there any documentation of the documentation?
1 Like