Season of Docs proposal for MicroPython

General discussions and questions abound development of code with MicroPython that is not hardware specific.
Target audience: MicroPython Users.
Post Reply
User avatar
mattyt
Posts: 410
Joined: Mon Jan 23, 2017 6:39 am

Season of Docs proposal for MicroPython

Post by mattyt » Tue Apr 16, 2019 2:30 pm

Hi folks,

Google announced their Season of Docs initiative a month ago; it's an effort to help improve Open Source projects' documentation.

The concept: An Open Source Organization applies to Season of Docs with a proposal for improvements to their documentation. Google also receives applications from Technical Writers and, for accepted proposals, Google will connect an organization with a tech writer. The tech writer will work with a nominated Mentor of the organization for three months to improve the documentation. Google pays the tech writer a stipend for their efforts.

I felt it was an opportunity we should pursue.

With Damien's input and feedback, I've put together a Season of Docs proposal for MicroPython that lists some of the key areas where we feel the MicroPython documentation could be improved. We think the proposal is in good enough shape to submit but I wanted to first share it with the community and open it up for comments.

Also, I've not prioritized the ideas; we don't yet need to but I'm curious which of the ideas are most important to you.

Thanks for any feedback!

kevinkk525
Posts: 969
Joined: Sat Feb 03, 2018 7:02 pm

Re: Season of Docs proposal for MicroPython

Post by kevinkk525 » Tue Apr 16, 2019 3:27 pm

This is very good and covers exactly what I was missing in the micropython environment! Thanks a lot. Hopefully that'll work out.
Kevin Köck
Micropython Smarthome Firmware (with Home-Assistant integration): https://github.com/kevinkk525/pysmartnode

P@T
Posts: 33
Joined: Tue Nov 06, 2018 2:37 pm

Re: Season of Docs proposal for MicroPython

Post by P@T » Tue Apr 16, 2019 5:07 pm

That's perfect !
With these details we could contribute more easily

Thanks

chrismas9
Posts: 152
Joined: Wed Jun 25, 2014 10:07 am

Re: Season of Docs proposal for MicroPython

Post by chrismas9 » Tue Apr 16, 2019 11:25 pm

That's a great idea. I have a couple of suggestions for the library documentation.

1. Where there is a port specific additional feature add a hyperlink in the common docs to the port specific docs. That will allow you to work from the common docs without having to check the port specific docs every time. The features don't need to listed in the common docs - just a one liner "These ports have additional features: STM32 nRF".

2. Some library functions have example code, but it is incomplete and often pyboard specific, eg using "X" or "Y" pin names. Provide more comprehensive examples. For example some classes have a deinit method, but to disable a timer interrupt you have to set the callback to "None". That's not intuitive to me and Google, Stack Overflow, etc didn't help. I needed help from Damien to figure it out.

nekomatic
Posts: 37
Joined: Thu May 08, 2014 9:31 pm

Re: Season of Docs proposal for MicroPython

Post by nekomatic » Fri Apr 26, 2019 1:22 pm

This is a great idea - I hope it's successful.

For me the highest priority looks like getting the user documentation for the popular ports into better shape. With luck that would serve as a model for the documentation of other ports.

benob
Posts: 2
Joined: Mon Apr 29, 2019 10:16 am

Re: Season of Docs proposal for MicroPython

Post by benob » Mon Apr 29, 2019 10:23 am

I would love to have more documentation on developing native modules. I have had to read the source code a lot, which is very instructive, but a proper walk of the subset of the internals necessary for writing modules using built-ins and custom types would be a nice time saver (chapters on that mater in lua's PIL are nice).

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

Re: Season of Docs proposal for MicroPython

Post by mattyt » Mon Apr 29, 2019 1:00 pm

Thanks everyone for your feedback; I submitted the proposal and we should find out if it's been accepted in a couple of days. Apparently a large number of proposals were received - so we're going to need to be a little lucky too!

As an aside @benob, I intend to submit a PyCon AU talk about Extending MicroPython; if accepted I will cover some of the material you mentioned. We still need it documented but a talk wouldn't hurt either...

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

Re: Season of Docs proposal for MicroPython

Post by mattyt » Wed May 01, 2019 4:21 am

The organizations selected for Season of Docs have been announced; unfortunately MicroPython isn't among them. :(

There were nearly 200 organization applications received and 50 selected for the program. I'm disappointed but focusing on the positives to come out of this process...

First, congrats to the selected organizations! I use many of those projects and I'm excited to see what improvements will be made from this initiative.

Second, it forced us to think seriously about the MicroPython documentation and the improvements we can make; we now have a list of tasks we can work on. Personally I think that improving the downloads page gives great bang for buck so I'm hoping to tackle that at some stage...

Finally, I do intend to re-apply for the next Season of Docs if/when it comes about. The current proposal gives us a great start - and we can read and learn from the other submitted proposals.

Thanks for all your feedback and support, I'm sorry it wasn't the result we were hoping for but we can still make the improvements ourselves and will try again next time!

User avatar
marfis
Posts: 215
Joined: Fri Oct 31, 2014 10:29 am
Location: Zurich / Switzerland

Re: Season of Docs proposal for MicroPython

Post by marfis » Wed May 01, 2019 5:03 am

sorry to hear it wasn‘t selected & thanks for the initiative!

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

Re: Season of Docs proposal for MicroPython

Post by stijn » Wed May 01, 2019 7:54 am

Thanks for the effort anyway, and maybe next time..

In general it seems the choices were made for the somewhat larger, even huge, projects and perhaps that is why MicroPython was not chosen?

Post Reply