@Stiltjack
I know it’s a group thing, and I have no problem pulling levers on links, but I thought the top description of the cookbook page needs help. When you reference the link, it pulls in a paragraph un-formatted with the beginning of the links. There is the lead sentence, then it starts with the links that get jumbled.
My thought is someone good with words such as yourself could make the paragraph longer so that it is a better explanation when you hand someone the link to the cookbook itself…
Looks like this here:
And looks like this everywhere else:
So filling in a longer paragraph at the top with a longer excerpt would help overall.
If someone else wants to take a shot, fine with me as well. It just needs help.
It’s fine original.
Look at the pictures of external links…
If we add to the first line an excerpt, the explanation shown on external links will be more presentable.
I’m enjoying the cookbook since it gives me a lot of good ideas on what I can do with home assistant and it jumpstarts many projects.
My contribution to the home assistant community is writing and updating guides. Two of them made it to the cookbook so far.
What is still missing?
Maybe we can use this topic to gather and vote on suggestions.
I hope this inspires others to help with writing good and complete documentation.
Heads up with editing the Cookbook.
It appears Discourse had a limit on how many of the auto-title links in a post. You know, the ones where you drop the link and add a “.” at the end so it displays pretty…
The cookbook is at the limit, so every new link added should use the
[link display](link)
nomenclature going forward.
Otherwise you add your link then someone has to come around and fix the oldest link that is now displaying the URL instead of the pretty words…
It’s happened to me a few times and I have fixed it already when others have added links, so be aware.
I hope they’re going to upgrade the forum soon. My weather integration guide is uneditable because changes to tables can duplicate part of the code. These inconveniences and restrictions cost a lot if time and withhold (newer) users from contributing.
Fix what, changing the Discourse page generation code?
We just need to use the html code because there is a limit on how many they do for us. This would not be a configuration parameter, rather just how it’s coded.
I could fix it now by editing the doc and converting a bunch then people could add new links for a while the easy way, but people adding links can just as easily code it when they put in new ones. Someone added one a couple of days ago and it went well for them.
So I get alphabetical, etc…
The big problem is that I have given out quite a few links to the zigbee section and now you have broken all those links. The Zigbee link is now different as Discourse adds a number on the end to keep the links unique within the document, even if the heading words are the same. The number is a count from the top of the document.
instead of 18, zigbee is now 20…
We have to think about adding sections and re-arranging sections for the sake of re-arranging them, these actions have a ripple effect…
It’s probably been broken before and I didn’t notice it, and I’ll get over it, but another thing to think about…
Ok I’ve added it to the links, however I really don’t think it’s helpful as-is. My goal was to get it to a state where people could throw stones first, and then ask if it was useful to include.
Unfortunately I wanted to post something else and apparently you can’t have more than one topic as a draft, so I had to post it first.
Work in progress, but already worth reading. It doesn’t need to be complete to add value.
I wouldn’t mind adding it to the index and putting in some effort to polish it up. @mekaneck: do you want some help with that?
It’s fine if you want to finish it yourself first. Whatever you prefer.
Good idea to suggest that readers open links in another tab. Is there a way to make links do this automatically (as with html target=“blank”)?
As far as I can see, readers either have to set this in their preferences, or right click and select “open in new tab”. Perhaps someone more familiar with Discourse can tell me I’m wrong?
Edit: Been through the Entities section, mostly adding white space. I think this is important, otherwise posts become as impenetrable as the docs!
@AJediIAm Its in the index under #2 (getting started with HA). I think that’s the appropriate spot. I’d welcome edits from you or anyone else (thanks @jackjourneyman and @parautenbach already for edits) however I’d prefer to finish the basic content creation myself first before taking large chunks of content from others. It’s mostly stream-of-consciousness writing at this point and I’m not spending much time polishing what I’ve written (will do that later unless others get to it first like is already being done, which is great). I’ve got a bit of a path already in my head and would like to get it all written down first. At that point major content additions (or other deletions or more massive changes) will be fine. Just trying to not get knocked of the path that’s in my head. But once it’s on paper, it may become apparent that it’s not the best path anyway and so big changes are warranted.
And, as is becoming apparent from that text block, my white space skills do really need some work
