Docs: a start on an 'improve this page' feature #136246
Conversation
nedbat
force-pushed
the
nedbat/improve-docs-page
branch
from
b8f50bc to
673e347
Compare
|
|
||
| - You can start a discussion about the page on the Python discussion forum. | ||
| This link will start a pre-populated topic: | ||
| `Question about "PAGETITLE" <https://discuss.python.org/new-topic?category=documentation&title=Question+about+%22PAGETITLE%22&body=About+the+page+at+PAGEURL%3A>`_. |
There was a problem hiding this comment.
I think we should use the path here, as otherwise it can be ambiguous, e.g. there are several Introduction in the docs.
There was a problem hiding this comment.
Try the live version in the preview build. The body gets populated with the URL.
There was a problem hiding this comment.
I see, the issue one however does not work for me, it sends me to the choose a template page. I also think good titles would be nice for triage/finding purposes.
| `Docs: problem with "PAGETITLE" <https://github.com/python/cpython/issues/new?title=Docs%3A+problem+with+%22PAGETITLE%22&labels=docs&body=The+page+at+PAGEURL+has+a+problem%3A>`_. | ||
|
|
||
| - You can `edit the page on GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_ | ||
| and open a pull request, though you will need to have signed a contributor agreement before it can be merged. |
There was a problem hiding this comment.
Just a little note, I think mentioning the contribution agreement here may scare away people, as it does not explain much about it, and does not pop up when they edit the page.
There was a problem hiding this comment.
Yes, I was torn about putting it here, we can drop it if needed.
|
I like the "This link will start a pre-populated topic:" link, but I wonder whether "less is more" applies here. In particular, I mean if the "Improve this page" link directly goes to the pre-populated Discourse form, would that more directly get users to where they can make a suggestion? If so, would it be better for "Improve this page" to link straight to Discourse? |
I'm not sure Discourse is the right place for everyone. Some people will have edits, some will have questions, some will want to discuss ideas for improvement. I appreciate the desire to make the path as well-greased as possible. If we do decide to link straight to Discourse, we'll need to change the link from "Improve this page", because Discourse is not the place to do that directly. |
At the Docs WG meeting, we talked about smoothing the path for people to suggest improvements to the docs. This is a start. It uses more JavaScript than we are used to.
I haven't done anything to trim down the "Report a bug" page. Ideas welcome.
📚 Documentation preview 📚: https://cpython-previews--136246.org.readthedocs.build/