Raising documentation issues

General discussions and questions abound development of code with MicroPython that is not hardware specific.
Target audience: MicroPython Users.
paulg
Posts: 29
Joined: Fri Oct 23, 2015 1:06 pm

Raising documentation issues

Post by paulg » Mon Jan 20, 2020 5:56 pm

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?

User avatar
tve
Posts: 104
Joined: Wed Jan 01, 2020 10:12 pm
Location: Santa Barbara, CA
Contact:

Re: Raising documentation issues

Post by tve » Mon Jan 20, 2020 6:19 pm

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...

User avatar
pythoncoder
Posts: 4030
Joined: Fri Jul 18, 2014 8:01 am
Location: UK
Contact:

Re: Raising documentation issues

Post by pythoncoder » Mon Jan 20, 2020 6:29 pm

Pull requests (PR's) are the approved way to do this.
Peter Hinch

User avatar
jimmo
Posts: 1440
Joined: Tue Aug 08, 2017 1:57 am
Location: Sydney, Australia
Contact:

Re: Raising documentation issues

Post by jimmo » Wed Jan 22, 2020 12:28 am

+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.

paulg
Posts: 29
Joined: Fri Oct 23, 2015 1:06 pm

Re: Raising documentation issues

Post by paulg » Wed Jan 22, 2020 5:15 pm

Thanks guys, I will follow your advice and raise a PR. Thanks to jimmo for providing an example.

paulg
Posts: 29
Joined: Fri Oct 23, 2015 1:06 pm

Re: Raising documentation issues

Post by paulg » Wed Jan 29, 2020 5:56 pm

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.

jedie
Posts: 247
Joined: Fri Jan 29, 2016 12:32 pm
Contact:

Re: Raising documentation issues

Post by jedie » Wed Jan 29, 2020 7:11 pm

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.

paulg
Posts: 29
Joined: Fri Oct 23, 2015 1:06 pm

Re: Raising documentation issues

Post by paulg » Thu Jan 30, 2020 9:38 am

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.

Online
stijn
Posts: 429
Joined: Thu Apr 24, 2014 9:13 am

Re: Raising documentation issues

Post by stijn » Thu Jan 30, 2020 10:21 am

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?

jedie
Posts: 247
Joined: Fri Jan 29, 2016 12:32 pm
Contact:

Re: Raising documentation issues

Post by jedie » Thu Jan 30, 2020 11:18 am

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 223 times

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

Post Reply