MicroPython
Micropython web pages, add **User Contributed Notes** #11854
Replies: 6 comments 3 replies
-
|
I voted no and feel I should explain my position. I have found such user contributed notes to be a poor addition to any documentation - they are typically poorly curated and, as such, are often wrong and misleading. That PHP link provides a good example IMO; there are many entries of very dubious quality. I think it significantly reduces the quality of the documentation. I'd much prefer any efforts of user-contributed content to be focussed on the MicroPython wiki. There are some useful pages there but we do need to do a better job of editing and organising. |
Beta Was this translation helpful? Give feedback.
-
|
I also voted no, primarily because it would create an additional moderation burden for the MicroPython team. It would also require a change in the existing document workflow: Sphinx doesn't seem to support a discussion extension. |
Beta Was this translation helpful? Give feedback.
-
|
The official documentation could certainly benefit from more examples, especially small snippets of how some parts are supposed to be used. I still voted no though, because it is one thing if the documentation is a bit scarce but much worse to have non-working, outdated or very bad practice in there. So curation and moderation is necessary, along with keeping things up-to-date if an API changes. |
Beta Was this translation helpful? Give feedback.
-
|
Hi The idea is to have a agile way to add comments, caveats, pitfalls etc... to each page of the official docs. I see your doubts but I have to disagree, they aren't strong: That PHP link provides a good example IMO Don't lump all the grass together. additional moderation burden for the MicroPython team No. It should be an unmoderated space. It would also require a change in the existing document workflow: Sphinx Yes, and for me it is the weakest of arguments. Sorry but there are a thousand possible solutions, just have the will to implement them. At the moment is a burden for us users:
Just in the 'micropython' repository, we are at almost 5000 issues ad 12000 discussions. Do you think this is an efficient solution to easily find up-to-date information? Example Some weeks ago I reported a fallacy in the official docs (the number of arguments permitted in @viper functions). Today reading the official web page Functions may have up to four arguments IMHO the current work-flow is a burden for the maintainers, and too slow to keep up-to-date with the Micropython developments. With my idea, everyone can publish their discoveries and they are immediately visible. |
Beta Was this translation helpful? Give feedback.
-
|
You're linking to outdated docs from 2017. The Viper code emitter section no longer refers to the four argument limit in the latest version.
StackOverflow sites are heavily moderated, and the volunteer burden is high. Having the will to implement your solutions is one thing. Having the people, time and money to do so is quite another. |
Beta Was this translation helpful? Give feedback.
-
You have your opinion; I have mine. That documentation is worse for those comments, to me.
Hard disagree. Official documentation should not contain any unmoderated content IMHO. We have to at least defend against spam and, from my experience moderating the MicroPython wiki when it was hosted on Mediawiki, this still requires significant human intervention even with modern tooling. Let alone moderating for correctness in posts.
I agree that there are other solutions. But the benefit has to outweigh the cost of moving - it doesn't IMO. Further, Sphinx is practically a defacto standard in the Python community; as such, it's very compelling since a larger pool of developers can contribute to the documentation.
I think the burden is exaggerated. Users can report problems in discord, issues, discussions, PRs. Documentation issues - particularly if they're simple corrections - are usually dealt with promptly. The bigger problem is that only a small number of people know enough to create accurate documentation. The proposal doesn't change that.
Those numbers are misleading/incorrect. Of the 5000 total issues, only 1300 remain open and, of those, only 18 are marked with the docs label. There are a further 15 open docs PRs. Even considering that some tickets may not be labelled correctly, this doesn't seem too out-of-control, particularly for a project of this size. The number of discussion topics is much smaller than 12K - the number assigned to a discussion topic does not indicate the count (the unique ID is shared between other tickets, such as issues and PRs). It's closer to 1K - the discussion board on Github is relatively new.
Um, yes. There is a lot of content on the Internet. 😛 |
Beta Was this translation helpful? Give feedback.
-
|
I just also voted with NO. I'm strongly afraid that unmoderated contributions in official docs lead to pollution of this information space. At the same time I agree that it is desirable to collect valuable pieces of information from the discussions on GitHub and from it's issues and pull requests. But this should be somehow moderated. Not necessarily by the experts, but by someone with the desire and commitment to do so. If you feel you would like to go for it, feel free to start such a collection on your GitHub account and invite people to add their insights, comments and improvements on it. Once it has grown and is a valuable source of information, with some structure, it may be referred to by the official docs and in the GitHub discussions. Much like, for example, the tutorials on asyncio by @peterhinch. |
Beta Was this translation helpful? Give feedback.
-
|
@massimosala If someone wants to contribute to the documentation the whole point of having our documentation in GitHub is that it is trivial to send a PR to make small fixes or improvements. Exactly like the example you gave about the viper argument limit, it took me about 5 minutes to make that PR (about the same amount of time as it took for you to raise the bug!). I agree with @mattytrentini that the Wiki is a good mechanism for more informal content, and maybe we could establish some conventions for linking to Wiki pages from the documentation. |
Beta Was this translation helpful? Give feedback.
-
|
After thinking this over and reading the above I also voted no, for the reasons detailed by others. As for the Wiki, the wiki connected to the forum was very neglected containing a lot of out of date content. I never felt I had the authority to delete such material. A wiki, if widely used, needs moderators. Otherwise it gradually rusts. |
Beta Was this translation helpful? Give feedback.
-
Reading thru the open issues, I find many good ideas... getting lost in the ocean.
I mean, users have to dig thru the issues to eventually find comments on the feature of interest.
I propose on every documentation web page to have a free User Contributed Notes
See for example:
https://www.php.net/manual/en/function.eval.php
It seems to me an effective solution to collect the various side-effects, caveats, inconsistencies in the docs.
Or just some nice advice on using modules / functions.
Each user can easily make her/his own contribution.
The section is called User Contributed Notes so it is clear that the comments are user feedback and ideas, unofficial but IMHO helpful.
If you read PHP pages, you see the effectiveness of this type of content.
16 votes ·
Beta Was this translation helpful? Give feedback.
All reactions