The HA docs already have a link to their github source (“Edit this page on github”), but not everyone is good at git and not everyone will know that an edit link will allow them to see version info/history there.
Following a discussion elsewhere here I propose generating the date or commit number (or some other versioning info) of the doc page on the page. This would presumably involve minimal/one off programming as the pages are automatically generated. Therefore one code change should be able to generate every page with a bit of extra info.
Idea extension: link to last two or three versions.
I’ve just tested getting this date into the page.
While it works, it is an expensive I/O operation and increases the build time for our website with 3008.3%, which I consider unacceptable for such a feature.
I certainly do not have an understanding of the code used to generate the updates, but I do not see how adding a place holder under each title for the revision and date would add to the build time.
\\ Automating Home Assistant
Revision: xxx Date:
I have been using Home Assistant for a little over a year and I have never saw any link on the document(s) page (s) that show you anything to do with revision, changes etc to the document. The only links I see is edit this page on github and links to other documents. Again, I’m sure it is clear to you and other users, but it has not been clear to me. I have found if you go to edit on github you can get to a commit page. This list what code changes effect the document, not the changes to the document itself. These are two different things and both need to be tracked. Changes to documents are not usually from code changes, i.e, spelling, formating, new feature, etc.
I guess something is getting lost in our back and forth. What you link to me is not a document change history. I went to an easier one automations and the first several items have nothing to do with the automation document.
Examples of document changes:
Document formatted to add clarity.
Example added for new feature.
Fix Spelling error
Item x removed due to code change
Only changes to the document are included on a revision page. It should be clear to any reader what changed and why.
At my last company, the second page (after title) was called the revision. This listed the revision, date, why changed. This was fairly easy and any new engineer (or college intern) that we hired could do this after a very brief training.
Code changes are /were a lot more complicated. There you listed the revision, etc but then you had to list all the documents, customers, and other code that the change affected. I agree this is very time consuming, but again a necessary item.
I am not here to argue with you, but this is far from clear to anyone on the outside. For example, someone in one of the forums was complaining about how he lost all of his comments in his automation.yaml. This was changed a long time ago, but it is not easy to find when the document was changed and the note was added to the bottom of the page saying this was going to happen.
I’m not arguing, I’m trying to explain and think along solutions that are fitting as well. Hence me testing with a change today if we can get some data into it and and seeing what the consequences are for doing that.
The process is public, transparent and fully logged. I agree that navigating that is not for everybody, but the data, changes and revisions are there, in great detail, dating back to the start of the website for each letter changed.
Unfortunately, that example is not really a good one. As this has always been the case and did not change
But yeah, I get your point, however, that said. Doing it manually is a recipe for not happening or being incomplete. Furthermore, it does indeed take a lot of effort, effort which I honestly think should be put into other things right now.
So you made my point. The documentation needed the revision noting the change. I’m sure the change was made prior to the documentation update. A lot of forum responses are "the code is released and then the document will catch up. " The more complicated HA gets the worst this is. A new user has no idea what information is valid or invalid.
unfortunately based on experience most open source projects suffer in the documentation area. It takes effort from all parties, devs, and community to keep it upto date and normally it fails
In regards to changes, if you look at the PR for changes they do have to check and/or update the doco. but sometimes the changes are not always in sync with the release, rare though
That is probably related to older changes. One of my personal efforts the last year is to manage that and it has been effective. Documentation on code changed is managed now. For example, a code change cannot be merged/accepted if the documentation is missing (by automation, the code build will fail).
That is a good change! Is this documenting code change as well as the top level doc?
I find it hard to find all that is current to what I am looking to implement on my system. If you do a search in the forums or YouTube most of the information is outdated. If the goal is for high end hobbies it is fine the way it is being done, but if HA goal is to be geared to a " plug and play" user it will be impossible for this user to find how to do most things.
I think due to the fast pace of HA development the forums and youtube will be outdated fairly quickly.
We have the same issue where i work with Microsoft Office 365, the whole ecosystem changes very rapidly and trying to train end users and even ICT support staff of all the changes using our own developed material was pointless as it outdated fairly quickly. In the end we point them to the official MS documentation. Which funnily enough is github hosted also and can be edited by anyone to make it more relevant. so even MS relies on the community to help with documentation.
It is related (and not controlled by anyone). As I have said there is no way for a user to know which document is current. When people implement new things (at least my procedure), I look first at the HA docs ( which are controlled). If I don’t understand or if it is not working how I think it should I search the forums, and discord and if I need further help I try YouTube. Again I don’t know which is the latest information.
If you are using yaml mode:
