Page 1 of 2

Raising documentation issues

Posted: Mon Jan 20, 2020 5:56 pm
by paulg
I see that the documentation has been updated over the holiday season and is much improved. Thanks guys!

However, I have noticed a few places where things are missing or more explanation would be useful.

Is there a single place where one can post suggestions for improvements to the documentation?

Re: Raising documentation issues

Posted: Mon Jan 20, 2020 6:19 pm
by tve
Have you considered creating pull requests to fix the doc issues? You can do that on github without having to download anything, only takes about 10 clicks...

Re: Raising documentation issues

Posted: Mon Jan 20, 2020 6:29 pm
by pythoncoder
Pull requests (PR's) are the approved way to do this.

Re: Raising documentation issues

Posted: Wed Jan 22, 2020 12:28 am
by jimmo
+1 -- PR's are the best way to do this. Here's a very recent example from Peter: https://github.com/micropython/micropython/pull/5553

But, if you don't want to do that, it's still helpful to raise issues on github, so at least the suggested improvements are tracked.

Re: Raising documentation issues

Posted: Wed Jan 22, 2020 5:15 pm
by paulg
Thanks guys, I will follow your advice and raise a PR. Thanks to jimmo for providing an example.

Re: Raising documentation issues

Posted: Wed Jan 29, 2020 5:56 pm
by paulg
Guys, I followed your advice and failed miserably.

I signed in to Github, went to micropython/micropython, selected the Pull request tab and clicked the New pull request button. I then got a Compare Changes screen with the Create pull request button greyed out. What do I do now? I don't want to change any code so I've got nothing to compare against.

I looked again at Peter Hinch's PR. It's not really a good example. He references an issue with machine.RTC.rst so he has something to compare against.

The help documents don't seem to cover my scenario and I am going round in circles.

I appreciate that you all mean well, but tested and proven suggestions would be appreciated.

Re: Raising documentation issues

Posted: Wed Jan 29, 2020 7:11 pm
by jedie
Create the pull request ist the latest step.

Easiest way is to browse to the source file and edit it on github. That will fork the repro and created a branch like "patch-1" and then you can create the pull request.

Re: Raising documentation issues

Posted: Thu Jan 30, 2020 9:38 am
by paulg
Thanks for your reply jedie, but it seems you haven't understood what I want to do.

I do not want to change any code. I just want to offer some suggestions for improving the documentation and was asking how best to do this.

Re: Raising documentation issues

Posted: Thu Jan 30, 2020 10:21 am
by stijn
If it's mere suggestions, open an issue on Github or post here on the forum.

Everything beyond that, i.e. you actually adding/improving documentation, does require changing files in the repository (whether it's considered 'code' or not is something else). And showing those changes to others/asking them for be to be merged into the main repository, means creating a PR. Are you sure that's not what you want to do?

Can you maybe just explain by example what you would actually want to do?

Re: Raising documentation issues

Posted: Thu Jan 30, 2020 11:18 am
by jedie
paulg wrote:
Thu Jan 30, 2020 9:38 am
I just want to offer some suggestions for improving the documentation and was asking how best to do this.
As stijn sayed, the documentation is a part of the source code repository, here: https://github.com/micropython/micropyt ... aster/docs

e.g.: The page "The MicroPython Interactive Interpreter Mode (aka REPL)" http://docs.micropython.org/en/latest/r ... /repl.html will be generated from this file: https://github.com/micropython/micropyt ... e/repl.rst

If you want to change something on this page, edit this file and create a pull request. Start point is here:

screenshot.png
screenshot.png (70.54 KiB) Viewed 633 times

Help about the workflow on github is here: https://help.github.com/en/github/manag ... repository