There certainly is 
https://developers.home-assistant.io/docs/documenting/
2 Likes
Awesome! Thanks for the link. Is that part of the documentation up to date? 
Frenck told me there are already tests with new documentation frameworks. But as far as I understood … we shouldn’t care about that and just start improving.
There was someone proposing a new section in this forum – is that something we could maybe start now to collaboratively workout rough ideas for new beginner guides etc. pp.?
For most changes you can get away with this:
You can use the " Edit this page on GitHub " link to edit pages without creating a fork. Keep in mind that you can’t upload images while working this way. You work on your change and propose it via a Pull Request (PR).
For heavier changes where you want to run a local copy of the website, I think they are up to date.
Earlier today I used the devcontainer that is included in the repository to make some changes and had no issues with that personally.
This one https://community.home-assistant.io/c/community-guides/51 ?
I guess that could work?
Anyone are free to open any thread in all categories, just find one that fits your needs 
1 Like
Lets not get bogged down with changing the documentation platform we have now or change control and revisions at the moment as we all know in real life there is a cost to that and this is open source project not a commercial entity.
What we need to focus on is doing it
I would be happy to submit a PR for someone who isnt confident enough to use github but is wanting to update the documentation. Submit it on forum, lets review it and lets get it changed
i think the next idea instead of WTH should be let stick it to the doco. get a month of people submitting changes and making it better.
At the moment were here in this tpost in a loop of this, that, not me its them, its all wrong. lets just get on with it
1 Like
It maybe on github, BUT, the link to the docs
https://www.home-assistant.io/docs/
https://github.com/home-assistant/home-assistant.io/blob/6827f0781a4acc4236d5dd6ffc4f93866870dbd1/source/_docs/configuration/yaml.markdown
Have no revision number or letter. If I click on edit this on github it is is not obvious (to me at least) on how the version control is done. How do I know what is changed? If I click on history it goes to yaml.markdown, not the yaml doc that I am looking at. The first item of
https://github.com/home-assistant/home-assistant.io/blob/6827f0781a4acc4236d5dd6ffc4f93866870dbd1/source/_docs/configuration/yaml.markdown
is #14,356. Does this mean that this document was revised over 14,000 times?
Most company documents that I have seen show the document Revision, i.e Rev B, C, EE, etc then a Revision sheet that shows what was changed Minor revisions, spelling, formating, etc are all incorporated when a necessary revision is made. It is rare that I have seen document revisions in the double digits (it happens but rarely).
I am willing to help write how the documents are done and controlled if someone can give me a better explanation of the process.
No it is the number allocated to the pull request commit that changed the document.
You really will have to get some idea of how github works I’m afraid. But every change ever to that doc is listed there. Some are minor typos, some reflect a mass change to a number of different files.
You’ll get used to it, but you do need to have some knowledge of github.
1 Like
Where can I find out how this is done? So when the document is changed, what is the revision number?
on history it shows you all the commits, those are the individual changes. click on one it takes you to the change
and you can see the what was added/changed (green) and what was removed (red)
the #14400 is the number of the pull request
I clearly do not understand how this works, are you saying that there were over 14,000 changes to a 1 page document? I also do not understand the numbering. The one before the 14,356 is 13,049.
No, it the number of the pull requests for the whole document repository.
Thanks. So how many changes to the Yaml doc for example?
there have been over 1500 changes to the WHOLE document repository sice that one and the next
why does it need a number, each commit listed on the history page for that one document is a change
No one should really care about this anyway, it is the current content (or lack of it?) that is important here.
But if you really want to know how it works I sugest you lookup basic information on git and github
Funfact, even Microsoft has their docs managed like this 
https://github.com/MicrosoftDocs
5 Likes
Not true. When I click on history there are changes that have nothing to do with the yaml doc.
A commit can change multiple files, iif you open one of them, it shows you the change to that document (and others if they are)
look at the links Lueeus gave about how github works
I don’t know if it’s necessary to pause a release cycle just for this, as this problem is honestly something the community is capable of handling entirely on their own. Much of the issues with the docs I would classify as low-hanging fruit; things that take very little effort and time to fix.
But I support your general idea. Just like we have the “month of WTH” going on right now, it would be nice to have an annual “month of Docs” or something. Teach people how to contribute to the docs, come up with a list of focus areas and some type of “style guidelines” so that everyone is on the same page, and then work together to fix all the issues.
In fact, coming up in October is something called “Hacktoberfest” which encourages people to get started contributing to open source projects by rewarding them with a free t-shirt and stickers after 4 pull requests. So if anyone wants to help out, that could be a little bit of extra motivation
5 Likes
Great idea!! An effort like this, especially the parts about helping beginners learn the ropes and prioritizing their efforts, might finally get some momentum in this area.
1 Like
This. Is what’s missing.
1 Like
Have you seen this?
2 Likes