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: 205
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: 359
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.

P@T
Posts: 3
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: 95
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.

Post Reply