It is amazing how fast Home Assistant is growing. I think a feature that is indirectly related to HA but one that many in the community would appreciate is a searchable main website for HA. I personally like the idea of a MediaWiki.
I know the current git site is able to be contributed to by the community but it requires a github account as well as being familiar with creating PR’s. A site that is more easily modifiable by the community would take much of the burden of documentation off of the dev’s and would allow for more rapid development both in the source of HA as well as documentation. I found Home-Assistant.wiki but it is currently basically empty.
I was curious if anyone knows if the current HA website might be able to incorporate a search feature.
I also like the idea of a more community-friendly documentation website. Additionally, much of the documentation I have looked at is outdated and there is not an easy way to provide feedback unless you’re familiar with GitHub.
This is the workaround for the missing search feature. For the search feature we are looking for a PR.
Nowadays, you can’t have a wiki without registration. So, you need to register somewhere. The current setup allows one to edit the side online (Edit this page on GitHub) which close to a wiki.
Well, if that’s the case then I’m wondering where all the reported issues are…Right, opening an issues on Github which requires a registration is so hard that most people fail.
My problem isn’t with registration, it’s with the process and the formatting codes, which are unique to GitHub.
If you could point out some references, maybe I could help. I’ve actually asked this before and never got a response.
If someone could write a short tutorial on HOW to update documentation, the process and some of the special codes for formatting, I’m sure some folks like myself would pitch in. I’ve spent time putting together tutorials here and I answer questions all day long so you know I’d do it if I could understand how.
Also, for searching I have a bookmark of this URL:
I did not mean to offend – it just is not user-friendly for the average person. Case in point…
I believe what user Kbeesnees is looking for is a way to bridge the knowledge gap between the active development team, and the active community that’s building and growing here on the forums, reddit, social media platforms, etc.
@fabaff Thank you for the search workaround. I know it will be useful to me. I also did a bit more poking around git to get a better idea of how to edit pages. It does seem relatively simple and I’ll try my hand at it.
I did notice you mentioned opening an issue on git for documentation issues. Should this be the process or should we be editing the page and submitting it for review? I’m not sure if it matters.
@ everyone
In all honesty I suppose I like the idea of community filtered, edited, and driven documentation. It is important however to make sure documentation is accurate so I understand the desire to review changes prior to publishing them and I think that is what github affords over other systems in addition to being one centralized location for the code and documentation.
Honestly, my first experience with Markdown was creating the README.md for my HASS repository. I accomplished that by editing an existing one (that’s typically how I learn). My second experience was the page we made. Again, I edited an existing page as a guide.
One thing you can do in Github is view the “RAW” code for any of the pages, which helps immensely with the creating/editing for pages.
Submitting a PR is the only way to post a new page, but the “Edit In Github” makes it easy to make edits without having to deal with forking/PRs etc.
EDIT: Ignore this post and go read the excellent writeup by @silvrr located here
I would suggest just trying it.
I know it looks scary and complicated if you aren’t familiar with Github, but it’s not too bad.
First you need a github account. Once you have that, navigate to a page with errors, and (while logged in) click the “edit this page on github” link. - That will create a fork (a copy) for you, that is located in your own personal github repo. Edit this using the editor built into Github. The directions are on the edit page, and fairly easy to figure out. Once you are happy with it, save the edit (make sure to preview first). After saving, you will have the option to create a PR (a pull request) against the original document you selected to edit. (Remember, up until this point, you have been working on your copy, and not the original!) What this does is takes a copy of your changes, and submits them to the maintainers for a looksie (that’s the technical term). Github will tell you who it thinks should look things over. (In my experience, it is usually @fabaff, @balloob, and/or anyone who had edited that page previously). If everything looks good, your changes will be approved and will become part of the official documentation everyone else depends on.
The main thing to keep in mind here, is that your changes wont go live without someone who knows what they are doing approving them, so don’t worry about messing anything up! Just go forth and edit, and you will get the hang of it!
This is how open source usually works. If everyone contributes, we all become stronger as a result!
