Documentation

[UltraBob]

Is there any way to contribute to the documentation on Micropython that is on the micropython.org site? I find it to be really inadequate and inaccessible for someone new to dealing with microcontrollers, and as I learn more, it seems like a good way to contribute to the community, might be to add to the documentation. If there is no way now, is it a possibility for the future? I can't really help out much on the micropython implementation at this stage, but I could help out by filling in knowledge I needed to the docs as I learn it.

[dhylands]

My understanding is that the documentation for the APIs (like pyb.UART) http://micropython.org/doc/module/pyb/ is generated from the source code using this script:
https://github.com/micropython/micropyt ... /gendoc.py

[UltraBob]

OK thanks, so that makes sense. I probably should read through the source and try to do what I can to understand it before writing documentation anyway. I'll see if I can do that for some low hanging fruit when I have a little spare time.

[pfalcon]

There're also bug tickets which deal with the question of managing and contributing to documentation:

• https://github.com/micropython/micropython/issues/585
• https://github.com/micropython/micropython/issues/639

[pfalcon]

I find it to be really inadequate and inaccessible for someone new to dealing with microcontrollers, and as I learn more, it seems like a good way to contribute to the community, might be to add to the documentation.

Well, if you're new to microcontrollers it may be, just like you say, that you are not at the best position to write documentation . It's hopefully easy to agree that reference documentation should be focused and concise, or it will be hard to maintain and use. Tutorials are different matter, and the best approach is actually to post your initial steps and successes to your own blog, then share link here on the forum. That will make google be well aware of it too, and will help other novices with higher chance.

[UltraBob]

pfalcon, that is true if you want the documentation for the board to be accessible only to microcontroller experts. Personally, I find things like

pyb.sync()

Sync all file systems.

To be pretty ambiguous, at least to someone unfamiliar with filesystem operation code.

It seems like a little elaboration, such as explaining that it forces any pending write operations to be performed. Also, I'm not really familiar with the code base, so maybe in the context of the code flash means both the internal flash memory and the sd card, but from my really cursory look at the source code, it seems to be working only on the flash memory, not on

all file systems

My suggestion, was that maybe a set of eyes that is not intimately familiar with the code could help point out places where the documentation is insufficient.

I would hope that I would be able to look at the pyb module documentation, and figure out how to use the pyb module. They are currently too sparse, in my opinion, and the tutorials are extremely limited in what they cover. I agree that any documentation should be concise and focused. I also think it should be approachable, accurate, and usable. I'm happy to blog my experiences with the micropython blog (at least once I get my blog for writing on these kinds of things back up and going), but if I can help in a meaningful way to contribute back to the project, I'd like to do that in a way that helps out future people coming at things from my perspective.

[UltraBob]

and thanks for pointing out those github issues, it was good to read through those.

[torwag]

There is also the not yet so popular user wiki.

http://wiki.micropython.org/Home

A perfect place for user and beginner tutorials.
If something grows mature and becomes immense helpful, there is a chance it might be moved to some more official documentation, or a links are placed to point to it.

Guess, this is a good place for people to start with something.

[pfalcon]

My suggestion, was that maybe a set of eyes that is not intimately familiar with the code could help point out places where the documentation is insufficient.

By all means, and the example you give looks like a good case to be improved indeed!