I’d suggest to take a look at the provided statistics in the Cookbook. We can see, how often a link was clicked, and can work with that.
Once a month we can take a look at these and react by deleting some links, or add some interesting things in regard to what is often clicked.
I think, this is something that grows automatically. If we remind ourselves to delete some things from time to time, than we will be good to go.
And let’s not forget one thing: HA is a massive system, with lots of functions, that need to be explained. It’s more like a two or three volume book, than a “simple” topic, that we’d need to explain everything.
1 thing I wonder: the official docs were the place to go to and of course they need TLC and updated regularly.
Is the cookbook not turning in a copy of some stuff of the docs.
Of course one can be a supplement to the other and it doesn’t have to be a ‘fixed fact’ on how they evolve.
I’m just curious whether this has been considered…
Could be - it’s a danger we’ve talked over a few times. (This thread’s getting a bit long to find anything easily.) And you’re absolutely right, it shouldn’t. There would be no point.
Some of the docs are written as introductions - there’s a chain of pages about writing automations, for example - and in those cases the cookbook simply links to them. Most of the docs have a reference function, though, whereas the cookbook should be more practical how-to.
The original idea was that it would address practical questions that get asked all the time (@tom_l 's post on motion activated lights is a great example). The trouble is that questions get asked at lots of levels, so the answers are on lots of levels too.
There’s also the fact that the people who write the cookbook posts are interested in the technical stuff (obviously), so maybe some posts do drift towards the docs end of the scale.
This is why it’s important that as many as possible of the posts should be written as Community Guides. Anybody should be able to edit them and if they get too referencey hopefully somebody will change that. Maybe. Perhaps.
The formal docs describe what’s available. The cookbook are illustrations of common, practical cases (but not limited to) — about what’s possible. Where a lot of people struggle with technical docs is that they don’t know how to piece things together.
And also, it is not really easy for ‘commoners’ to edit/update the official docs (you need to do it through Github (PR’s), which is not that hard, but i don’t think there are a lot of users even having a github account🤔)
This is 100% true, the Cookbook should be an ever evolving document. Yes, it needs oversight(probably a lot), but limiting edits has already proved to be an issue. How many guides are outdated?
@Sir_Goodenough Do they ?
I thought only when they want to add custom repositories (and not even sure abt that either).
For sure it is not required when using HACS default…it is also not marked as requirement
Sorry, I might have given the wrong impression/not explained myself correctly…
I really think the cookbook is a good idea and so far, in my opinion, there is nothing that should be removed.
I have been asking myself what is the ‘best’ entry point for a newcomer in HA: the docs or the forum but maybe it should not be one or the other.
It would be a shame to do twice the effort to create and maintain.
I really wonder what the majority of newcomers are doing: starting from the docs or the forum.
TBH: I think I was more active in the forum from the start then reading the docs but then again, they were not as good as today.
In the end, the most important thing is to make HA as easy as possible to start with (which of is happening all the time), to maximize the experience and avoid having to answer the same questions over and over again.
Of course, this will happen somehow but with the number of installations growing, you don’t want the questions to follow that trend.
We don’t see what are hopefully the successful ones. We see the ‘Will this Pi3 work with a docker or VM’ kind of weird stuff and they have no idea what any of that is, saw in on YT or reddit or random forum posts stuff.
My thought on what the cookbook is about is that they run across a link or one of the posts and that gives them a curated list of things we thing they might run into. There they get advice and links to the actual docs.
I just had a thought. Maybe add a sentence to the cookbook index link to more invite people to see the whole list if they find one of the linked topics. It hangs there like a link, named OK, but I don’t assume that people are knowing what that link to the index will get them.
This would be a good one if someone wants to test this out and get some screenshots of it. Apparently if you are installing, or loading a backup, long running things like that, you can go to the CLI and do this to watch what is happening, I haven’t tried it, but hate it when installing and it tells you nothing. I’ve left mine sit a few hours so I wouldn’t mess up the install or backup recovery because I didn’t know this was possible… Discord.
Someone that can spool up instances easy would have to write it up, I don’t have the hardware or run a VM
I have seen lots of questions like is it still doing something, how long does this take, when can I open the webpage, it’s broken, etc…
