MicroPython Forum (Archive)

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!

This is very good and covers exactly what I was missing in the micropython environment! Thanks a lot. Hopefully that'll work out.

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

Thanks

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.

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.

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

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

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!

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

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?