Season of Docs : MicroPython

General discussions and questions abound development of code with MicroPython that is not hardware specific.
Target audience: MicroPython Users.
Post Reply
jnanjeky
Posts: 4
Joined: Mon May 11, 2020 6:26 pm

Season of Docs : MicroPython

Post by jnanjeky » Mon May 11, 2020 8:21 pm

I see that Micropython was selected for the season of Docs.

Joannah here, a Python core dev and contributor to other Python open-source projects.

I want to use GSoDs to help write docs on the internals of Micropython.

Happy to hear from you so I can share a plan I have in mind.

Best,
Joannah

torwag
Posts: 219
Joined: Fri Dec 13, 2013 9:25 am

Re: Season of Docs : MicroPython

Post by torwag » Mon May 11, 2020 8:26 pm

Hi,
sounds like a neat idea. I do some teaching with Micropython for some classes and albeit docs for usage are available exactly the internals are the most difficult part to find information about. Second to this would be documentation how to port Micropython to another board or another architecture.
Would be happy to hear about your ideas.

jnanjeky
Posts: 4
Joined: Mon May 11, 2020 6:26 pm

Re: Season of Docs : MicroPython

Post by jnanjeky » Mon May 11, 2020 10:00 pm

Actually, I was motivated to work on this because I was looking for internals information for MicroPython after the Python language summit at Pycon last year(2019).

I did not think of the part on how to port Micropython to another board or another architecture but I think it makes sense to be covered as part of this work.

Now, If no one is working on this as a project, I propose to use the following plan of action:
- Use the next three weeks to tinker some more and come up with an outline. It would be two but I have a research paper to write this week.
- Submit a PR for the outline for review.
- The community gives suggestions on the outline.
- If the PR is approved, I start writing based on this.
- we can follow GSoDs timelines.

I think we will just add another section here: http://docs.micropython.org/en/latest/ named "MicroPython Internals".
Last edited by jnanjeky on Thu May 21, 2020 8:18 pm, edited 2 times in total.

User avatar
mattyt
Posts: 280
Joined: Mon Jan 23, 2017 6:39 am

Re: Season of Docs : MicroPython

Post by mattyt » Tue May 12, 2020 8:14 am

As Joannah has already revealed, MicroPython has been selected for the Google Season of Docs 2020 program!

For those that unfamiliar with SoD, it's an annual effort by Google - in just the second year - to improve the documentation of open source projects. There is a process where Organisations and then Tech Writers apply to be involved. Google selects from each group and assigns - and pays - a Tech Writer to work on the Organisation's documentation for around three months.

Currently the SoD program has selected the Organisations and is now accepting applications for Tech Writers. Work is scheduled to begin in August/September.

Jim and I, and many others, are excited at the potential improvements SoD could deliver for MicroPython! Please take a look at the Season of Docs Project Ideas - 2020 and please let us know if you have any feedback.

jnanjeky
Posts: 4
Joined: Mon May 11, 2020 6:26 pm

Re: Season of Docs : MicroPython

Post by jnanjeky » Wed May 20, 2020 9:58 pm

So I see three major areas to tackle for documenting micropython internals

- The core
- cross-compilation
- Porting

A more concrete outline of what I want to cover is developing as I dig deep. I am still investigating micropython core.

I was on the fence about including details on micropython-lib but another part of me thinks we can leave this out of internals documentation. what do you think?

SpotlightKid
Posts: 404
Joined: Wed Apr 08, 2015 5:19 am

Re: Season of Docs : MicroPython

Post by SpotlightKid » Thu May 21, 2020 1:03 am

I think the existing documentation has serious problems with accuracy. Many things are outdated, specific to a port or not specific enough (important differences between ports are not listed) or just plain wrong. That's one of the first areas, which I think needs attention.

rpr
Posts: 78
Joined: Sat Oct 27, 2018 5:17 pm

Re: Season of Docs : MicroPython

Post by rpr » Thu May 21, 2020 1:40 am

Let me first start by thanking both Matty and Jim on creating the Project Ideas documentation. I am in full agreement with the list of areas mentioned in the Ideas Summary Section. I think that list is in order of need and should be followed as much as possible.

Once you guys have a more defined plan of how you propose to proceed, please post here and I will be happy to help in any way as I'm sure that others will.

Fantastic job, both of you.

jnanjeky
Posts: 4
Joined: Mon May 11, 2020 6:26 pm

Re: Season of Docs : MicroPython

Post by jnanjeky » Thu May 21, 2020 8:15 pm

Thanks for the suggestions @SpotlightKid.

I agree, correcting this is a great first step. From the project list, I was looking at creating new documentation specific to micropython internals. That is what I understood. And am coming up with an exhaustive outline for this.

I will open some PRs correcting some of these current inaccuracies but there are ideas on the list that focus on improving current docs and am sure someone else can pick that up too.

Post Reply