search

SensorsIot / IOTstack

Docker stack for getting started on IOT on the Raspberry PI
GNU General Public License v3.0
1.44k stars 304 forks source link

Doc improvements #579

Closed ukkopahis closed 1 year ago

ukkopahis commented 2 years ago

doc/home-assistant: fixup markdown formating docs: move video links from Getting Started to README.md and the Wiki home page #Fixes #58 docs: add Troubleshooting.md. Resolves #180 docs: regression: fix broken "issues" link in Developers/index.md

Paraphraser commented 2 years ago

This change prompts me to make a suggestion. Occasionally, we get people popping up on Discord saying things like "I followed the video but it didn't work." The videos date from gcgarner days and we're a couple of menus down the track plus a whole bunch of other changes in the install/dependencies space so, all up, the videos are a bit out of date. They're still a good intro to the basic ideas but less useful as step by step how-to.

When someone complains about being misled I try to explain that videos necessarily capture a point in time and aren't routinely (or easily) kept up-to-date, whereas text doco can be fixed in a trice so relying on the written word is usually the better choice.

Perhaps there should be words around the video links as a kind of heads-up for this problem?

That said, I don't know that extra words will necessarily be helpful because I don't know whether the newbie user path is from this repo to the videos, or if people find the videos by Googling or searching YouTube, follow the links in the videos to gcgarner, and then finally arrive at this repo by which time it's all too late. Anyway, just a thought.

ukkopahis commented 2 years ago

Perhaps there should be words around the video links as a kind of heads-up for this problem?

Great point. I'll add some.