Editing the Documentation and Creating a Pull Request on Github

Tags: #<Tag:0x00007f327bd50868>

I have seen a number of people complain about the documentation at https://home-assistant.io/ (HA site). Great news! Everyone can edit it and provide improvements to the documentation. Next thing I likely see is that people don’t know how to create a pull request on Github. Great news! Here is a tutorial on how to do it.

First go to https://github.com/ and sign up for an account. Its quick free and easy. If there is a need for a tutorial for this to please post that feedback below. Otherwise sign up and sign in.


In the upper right of most of the pages on the HA site there is a “Edit this page on GitHub” link.


When you click that link you will be brought to a new page with contents of the page you wanted to edit. In the upper right there is a pencil icon, click it to edit the page.


On the resulting page you can edit the text. Use the existing content and reference the existing page for figuring out how to edit the content. Usually the page just needs some tweaking so you don’t need to start over, just add on or delete some text. I have no idea how to create a page from scratch, but I have submitted 2-3 requests that are now in place with little issue. Don’t get hung up that it will be to complicated or you don’t know how to create the formatting, its easy.

If your making a small change don’t worry about the standards, follow the precedent on the page and make the correction. If your making a large change/new page be sure to read the devloper docs before getting started. Link Below.
https://developers.home-assistant.io/docs/en/documentation_standards.html

Here I provided some updates to the page (removing highlighted text). I provided a quick title for the pull request and added my reasoning below. When you are done, click “Propose file change”


On the next page, click “Create Pull Request”


On the next page add any additional comments and if related to a pull request on the actual Home Assistant code (not the web page) add the info and click “Create Pull Request”


You’re Done!!! You just submitted your first pull request and contributed to improving HA!

If this is your first time submitting you likely will need to sign the CLA. This is easy to do and you will either brought straight to it or receive an e-mail to complete this step. Its as simple as reading and clicking another box.

From here you will get an e-mail stating that your pull request was submitted and it will identify some reviewers based on who has worked on the page in the past. You will continue to get e-mails with updates on the status as needed. Eventually you will get one that it has been merged and your changes will go live sometime after.

31 Likes
How to update documentation
General thoughts on (getting started with) HA (hassbian)
Getting nmap to work on windows and also able to detect an android phone
Zwave instruction are incorrect
New YeeLight 2 (white) aka YLDP05YL is supported
Remote VLC remote controller (via telnet)
Entity Button Card and call-service modbus.write_register
Error in Garadget docs?
Someone Please Update Snips.AI Help Pages
Updater component not working, what am I doing wrong?
Request re documentation
Cannot Access pi-hole
Automation condition - if a state of an entity hasn't changed
WTH should integrations usage and their technology be documented?
WTH should integrations usage and their technology be documented?
WTH should integrations usage and their technology be documented?
EXECUTE not ACTIVATE?
Enocean Temperature A5-04-01 wrong readings
Beginner friendly documentation
The future of YAML
Beginner friendly documentation
Use apt-get commands
How did you install Home Assistant?
Improving HA documentation?
How do I format the sent brightness command in MQTT?
Badges and State-Label
Running a script or command every 5 minutes
Workday sensor - remove_holiday not working
Hacktoberfest 2020
Improve documentation of components
Raspberry pi gpipo how to?
Hass user password
Suggestions for improving HA documentation
Broadlink RM-PRO and TC2 switch
Automation Old and New
Network In for systemmonitor in windows not working
Searchable Home Assistant site
Xiaomi Yeelight E27 bulb component
Mqtt "this integration has no devices" with tasmota connected to add-on broker
New Hass.io images, based on HassOS
RESTful Switch Documentation is wrong

Great, I think that would be great to have in documentation

1 Like

I agree. This is just the sort of thing that we needed to have written up. Excellent work, @silvrr!

@Danielhiversen - I’m not sure if you realized the meta joke you just made. :laughing: Wouldn’t adding this to the documentation be roughly the same process?

@silvrr - Thanks so much for this!

2 Likes

Great example of why everyone needs to submit pull requests. In making this little tutorial I made a few tweaks to the yeelight component as shown above to provide the example. As I was paying more attention to making the tutorial than the config example there were errors in it. (spacing and and a missed colon :flushed:)

@LeeJS to save the day! He submitted a Pull Request and fixed the errors which should go live shortly. This just goes to show that we need everyone to be helping with the documentation. Also I need to focus on one thing at a time so I don’t make people frustrated with my config errors. (Sorry @LeeJS)

My pleasure!

This is great. I have lots of my own documents I’ve stored at home which I’ve used to record how I’ve setup some zwave specific devices so I’ll see about moving them here.

2 Likes

one picture is not loading

Thanks, I think this needs an update anyway. Added to my todo list.

1 Like

Might want to add what to do if you have clicked “Propose file change”, but then notice something needs to be changed (say I noticed a mistake in my edit), prior to clicking “Create pull request”.
In other words, go back to editing before creating the pull request.

OK, I updated the first post with the current workflow. I wasn’t getting this done so I did it as I was making an edit and noticed an issue.

Future items to add:

  1. Creating a github account?
  2. CLA signing process?
  3. Editing after you have clicked “Propose file change”

If anyone is going through the steps and wants to post the steps/screenshots I will either add them to my post or link to your post.

You can edit them but the changes need to be approved and merged. It’s not the wild Wild West.

3 Likes

Thanks just created my first edit

1 Like

…and it was rejected for being classed as duplicating an existing example.

There will be no Hello World code snippets in this documentation :crazy_face: