Home Assistant Cookbook - Discussion Thread

No, no, thanks for contributing - let’s see what other people think.

It’s turning out to be a bit difficult to keep focused on the scope of the project. :grin:

1 Like

This is a great point!

For example, a team with cross training will have less gaps in the ability to produce positive outcomes when experiencing changes in personnel and operational needs.

This forum is no different as contributors will come and go !

1 Like

+1

Maybe we could have some “internal” list, where we keep these things, to maybe add them in the future. It’s not about the guide itself, it’s about taking it into the Cookbook.

Honestly, I’m here in this forum for quite a while, but I haven’t had one occurrence in the last years, where this would be needed or even asked for. So I think it’s safe to say, that this is not one of the TOP 50 things, we should add to the Cookbook, in my opinion! But I’m only one voice of many! :wink:

Not sure, if that is really needed. I’d argue we should make some kind of check for the guides, where we decide, if the guide is ready to be taken into the Cookbook, and if necessary get’s updated, not newly written. :slight_smile: But this is something, we should leave at least in parts to the author.

That’s why we need the edit function for others, to do these updates to a guide, even if the author is not available at that moment. :slight_smile:

It could also be that we’ve already added most of the obvious topics - maybe we should slow down now. :grin:

1 Like

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. :slight_smile:

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.

What about this one: Installing HAOS on a dedicated x86-64 PC - #11 by MichaelSidenius

Since there is a section about installation, this post is quite helpful for x86/64

It would need to be edited into a single Community Guide post.

OK, I will ask him to do it so he gets the credit for it.

I think the cookbook is a great idea! :+1:

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. :roll_eyes:

1 Like

As Stiltjack said, but to add my 2c:

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.

4 Likes

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🤔)

1 Like

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?

If they use HACS, they have a github account.

But they might not realize it.

Any nominations for items to be removed from the cookbook?

@Nick4 did you have anything particular in mind in your original comment?

@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 :wink:

My bad… guess I forgot I went through that (many many many years ago :P)

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.