Skip to content

Docs linkage from python.microbit.org #68

Closed

Description

@DavidWhaleMEF

There is a (temporary) discrepancy between editor and documentation, for the python.microbit.org hosted editor.

Currently the v1 editor has v0.9 MicroPython baked inside it. The latest version of docs at readthedocs is for the V1 MicroPython image. Thus our users will be confused when they try something in the web editor and the docs are different.

I know this is a temporary transient state that will be fixed soon. However, with new term starting next week and many teachers planning to use Python in their lessons, it would be great if we could paper over this transient state carefully to give them the best possible Python experience.

I wanted to suggest a (potentially quick) fix.

There is currently no way to get directly from the web editor to the readthedocs documentation for the language. Pressing the big HELP button takes users here: https://python-editor-1-0-0.microbit.org/help.html and I can't see a link to the official docs in there?

If users google for the docs, they end up at the V1 docs for MicroPython on micro:bit, which are the wrong version for the MicroPython currently baked into that web editor, and there are a number of API changes and bug fixes (new API methods in the docs, that aren't present in the baked-in v0.9 image).

My proposal would be, for example, to add a DOCS button to the editor, that when you click it, takes users to the V0.9 URL for the readthedocs (as it is V0.9 baked inside the web editor). I am sure that @carlosperate could ensure that our branch of the codebase that is published has the correct URL in it.

When the V1 MicroPython finally makes it into the web editor, all that we would need to do is to change the URL to link to the V1 read the docs.

I understand the reasons why we haven't baked the new V1 MicroPython inside the V1 web editor yet. But I think we do need a way for teachers and students to have an amazin Python experience from next week when schools return, where the editor they use actually performs the way the documentation describes!!!

P.S. When there have been differences between docs and editor, it has always caused an increase in support tickets for us, and some consternation from teachers who (quite rightly) can't understand how anyone could release an editor with non-matching documentation ;-)

Thanks

Activity

  1. jaustin commented on Aug 29, 2018

    @jaustin
    Contributor

    Thanks for the detailed report. The docs 'mismatch' has been something we've often discussed, and I'd actually like to consider rendering the docs for the baked in MicroPython version with each deployment, so we have, for example, python.microbit.org/v/1/docs/, but I think that's a larger change to the structures we have in the repo at the moment. It also doesn't solve the 'entry via Google' issue.

    The link we'd need to create is to https://microbit-micropython.readthedocs.io/en/0.9/ and I think just adding the 'docs' as a link inside the 'help' would work well (Sam's done something with the 'help' button at python.microbit.org/v/beta that would work well for adding a 'Docs' link)

  2. microbit-sam commented on Aug 30, 2018

    @microbit-sam
    Collaborator

    Ack

    @jaustin are you happy for me to add this to the current live (v/1) version? I'll use the same mechanism as in v/beta

  3. microbit-carlos commented on Jan 7, 2019

    @microbit-carlos
    Collaborator

    @microbit-mark if you are looking at updating the help file then this issue might be relevant.

  4. microbit-mark commented on Jan 7, 2019

    @microbit-mark
    Contributor

    We have a link out to the /latest docs in the help section of the editor,

    screenshot 2019-01-07 at 13 36 02

    so is this resolved for now?

  5. microbit-carlos commented on Jan 7, 2019

    @microbit-carlos
    Collaborator

    I think we need to change the editor to start pointing at the same version of the docs as the MicroPython version it contains. So in this case, it should point to https://microbit-micropython.readthedocs.io/en/v1.0.1/ and we should have the link updated together with the MicroPython version.

  6. microbit-carlos commented on Feb 26, 2019

    @microbit-carlos
    Collaborator

    Versioned URL to the MicroPython docs was added in #92 (thanks Mark!).
    This is not yet live, but will be soon (first in the beta editor and very very soon after in the primary editor).

    I'm closing this issue as resolved, but please feel free to reopen if something was not quite covered.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions