I seem to recall that there was some automated script that ran when I first singed up here (the details of which escape me) that guided me through some basics such as editing a post.
I’m really not sure why it is that newcomers fail to either take the trouble to do just a little reading before posting, and/or ignore the pinned post that’s atop the Users Forum and clearly instructs on code formatting.
I for one would favor a said automated script that encourages the newcomer to simply format a line of Python code, using the Markdown format.
I know that this would be a barrier to entry, but on the other hand, would save the countless times that everyone else has to post, “Hey, could you please format your code using blah blah…” which is simply adding noise to almost every new post.
Anyone else feel this?
To be clear, I’m advocating that this be compulsory, so that we all know that any new member has been guided on this simple operation and then ignored it, if said member still fails to format their code.
It would be a good idea to do something about this, to be sure, and there are a number of (non-exclusive) mitigations that could be explored (though keep in mind that I’m neither a Discourse expert nor a moderator/admin on this Discourse instance):
I assume it is possible to configure Discourse to send all new users a customized welcome message, which could contain this information. Users could ignore this, although hopefully they will see the notification on first login and read it before posting.
A more robust approach would be requiring users to actually do the bot’s tutorials (which teaches this, I think), or making a new short one that just focuses on a few issues specific to our instance (categories, tags and code formatting), and only giving users posting permissions outside of Welcome to Discourse! once they complete it. But that would need to ensure that users aren’t confused and frustrated why they can’t post, and may be too burdensome for new users, and complex to set up and maintain.
Giving a more community members who are trusted and experienced and have been helping users for a long time the TL4 trust level, which would allow them to edit posts to easily fix this; I found this particularly helpful on GitHub when triaging user issues. One downside: a few of the most dedicated members in this category, e.g. @cameron and @steven.daprano , mostly/exclusively use email (though conversely, since they view posts in plain text, its not as big an issue for them).
It might be possible to implement some sort of hueristic auto-detection for Python code and alert users accordingly if the advisory messages shown in the preview pane are extensible (or via a Discourse plugin). However, it seems likely many users will ignore them, given they are already presumably ignoring how their unformatted code looks now.
I thought something (maybe @willingc’s Python Help post?) was pinned up there last month, but I don’t see anything now. The screenshot at bottom is from today.
Due to attention on resolving an issue made more intense, in many instances, by anxiety about how to present the issue in English–which you may not speak even as well as you can program in Python, few people are going to read even a mildly intermediate How-To guide/post on their first visit. They came here for a different purpose.
A possible and proven remedy to the code formatting is to pin a post with a bold title like…
===>>>>> READ THIS BEFORE POSTING CODE <<<<<===
With a brief one-line introduction and no more than three How-To points of instruction. Just the one on backticks might be the workable limit. (Well… two actually, for code blocks and inline monospace.)
We’re getting a lot of traffic on this theme, could @admins or @moderators or a TL4 (TL3?) user please consolidate these? Václav’s post might be the best place to tuck them, although chronological order could make more sense.
Plain vanilla out-of-the-box Discobot isn’t a coder and apparently doesn’t provide this module in his tutorial. It may be a switched feature like include_code_guide but I did the entire Discobot intro series recently and there’s no code guidance that I recall.
By Leland Parker via Discussions on Python.org at 24Jun2022 00:32:
Cameron / Steven, do the plain text mails suffer from (1) stripped
indents and (2) curly quote conversion when code is pasted as body
content?
Well… that depends. I, of course, do the correct thing of reading
email with mutt, which gives me control over viewing HTML vs plain text Discourse sends messages as multipart/mixed, which contain both a text/plain and text/html part, and my config shows me the text/plain version.
The result is that when users do not fence their code or text outputs
with triple backticks, I still see the original indentation, and HTML
users and forum users… do not
I usually try to include the source text when I reply to such a message
(because it’s really obvious at my end), correctly fenced (or, my
preference, 4-space indented which achieves the same end but makes for
more readable plain text).
What’s the quote conversion thing? Is there something which
mistransliterates ASCII apostrophe/backticks to Unicode close/open quote
marks or the like?
Yes, Discourse automatically converts straight quotes to typographical quotes, which leads to problems if the code is later fenced (bad syntax highlighting) or used elsewhere.
Also, in addition to the missing indentation, there’s a fair number of other characters in the markup languages Discourse understands (mostly those in Markdown) that are often used and code and can result in wonky formatting. For example, the comment character:
# This is a top-level comment
will make a heading:
This is a top-level comment
Dunder names (__init__, __file__, __contains__, etc) are displayed as bold:
Yeah, code text can get pretty mangled if pasted “out of context” into the message body. It gets gruesome if fenced in a code block afterward.
Since so many members here are primarily or exclusively using mailing list mode, it seems like a good idea to survey the UX side effects for online and mailing list users. @steven.daprano, would you care to share your experience with code pasted directly into in the message body?
(I’d also like to know if my efforts to create certain layout features are creating unintended effects, but that’s not the topic here,)
Academic but informative point: the header triggers if there is a space after the hash sign.
(Use of top-level header should be discouraged, or scale them both down to a less “shouty” size.)
I’m not Steven, but I am one of those luddites who interacts
entirely in “mailing list mode.” What I’ve observed is that code
pasted straight into the post without any preformatting indicators
primarily seems to lose its indentation, though also some of its
line breaks (subsequent lines getting flowed into the previous
because they’re treated as part of the same “paragraph”).
It’s worth noting that even inline preformatting is suboptimal for
people used to exchanging complex code samples over mailing lists,
since proper E-mail can include them as MIME attachments and even
declare specific content types and file names, so that the examples
can be saved and run directly rather than requiring ham-fisted cut
and paste operations which may pick up extra whitespace or fight
with autoindenting in editors.
Note that my experiences may be further colored because I not only
rely on Discourse’s “mailing list mode,” but do so with a plaintext
console-based MUA rather than some fancy graphical HTML-rendering
client. I see that the messages I receive are multipart/alternative
including both a text/plain and text/html version, so wouldn’t be
surprised if people using HTML-based mail clients see an entirely
different representation that I do.
also some of its line breaks (subsequent lines getting flowed into the previous
because they’re treated as part of the same “paragraph”)
I’ve noticed this consistently when pasting code as plain body text into VS Code. I’ll get an impressive one-liner that, if it ran, would win a trophy from the Rainbow Magazine One-Liner column. (Speaking of nostalgic days with my TRS-80 Color Computer.)
While we’re on the subject, does this code sample seem humorous or patronizing? (I should survey new users on it instead of those of us who are all too familiar with the pains of “body code” but we’re on the topic at the moment.)
So fence your posted code like this:
```
<paste or type code here>
```
It will make the code look like this:
volunteers = 0
print("Posting with a reader-friendly code format...")
volunteers += 1
print(f"...will probably encourage at least {volunteers} person to help me.")
while True:
volunteers += 1
print(f"or maybe {volunteers} people...")
The sample doesn’t seem patronizing at all to me, no.
It’s worth noting that in the text/plain representation I received
of that message, I do get all the Markdown included (the underscores
for your separator, the leading greater-than marks for the
blockquoted lines, backslashes escaping the backticks you wanted
displayed, and so on). For me, it seems like a fine compromise
though, as I don’t have trouble reading Markdown (I may have a
strong preference for reStructuredText, but this is still plenty
accessible).
I guess the post unpins automatically for you. Maybe after certain time or after achieving certain “trust level”.
I think pinned posts are good just for a small part of users which really pay attention to various details of the forum.
I am sorry that I did not notice your earlier post. At this moment I cannot imagine a better way how to teach the new users how to post code. I think we should try to use the plug-in here. I can imagine that after fine-tuning the message being shown to the users it can work very well.
Should we @ notify administrators about the plug-in? I am guessing none of them really feels the troubles in helping the newcomers with their code.
Other ideas I have (not sure if they are possible in Discourse without too much effort):
Have reply templates to easily insert suggestions in replies to newcomers - like: code formatting, preparing minimal runnable code, including outputs and error messages…
Allow users of certain “trust level” and higher to edit beginner’s posts in a limited way - just to change formatting. - IMHO this is controversial and it will not help much.
My thanks to all who are supporting this – I think that moving this Forum forward in a positive way will be key to its success.
To be clear on the ‘Pinned Post’ to which I was referring, it’s this one…
… which I saw for some time, when I first joined, but I don’t recall if I dismissed it (having first read it and leaving it be for some period of time) or if it kind of becomes unstuck, so to speak, after some period of time – I think it’s former.
Said post is still pinned, for anyone viewing the Users Forum without being logged in.
Ah. Yes, I think that post unpins after you read it, maybe on a date.day() or a topics_originated.count() basis. With a bold headline and a short, easily digested instant toolkit for posting code the auto-unpin would be perfect.
When users are disciplined about posting formatted code, then we can use that awesomecopy-code shortcut that appears in the top right corner of the code block!
is not very helpful here. It says nothing about formatting code.
It starts with a link to About Discussions, or specifically the Python Discussions rather than the software itself. This is harmless but not really useful for new users.
There is a misnamed link to the Code of Conduct, which believe me, is in no way, shape or form a FAQ.
Then there are a bunch of UI hints, which are useful but irrelevant to the question of formatting posts properly or asking good questions.
There’s also confusion over the name: Discuss, Discussions or Discourse? Which is correct?
The answer about searching is poor:
“Discourse is perfectly searchable using Google”
Yeah okay, but how do I use Google to search Discourse? (Or Discuss, or whatever it is called. Not to be confused with Discord, which is completely different software.)
Although I have zero expectation that people will read it before posting, it would be nice to have a proper set of instructions for asking good questions, starting with right at the top how to format code. At least we could link to it when newbies post without reading it.
Moderators already have the ability to edit people’s posts. I hate hate hate that (anti-)feature. My words are my words, and are not for other people to change without my permission.
There is a fundamental problem with giving users the ability to edit their posts: you break the integrity of the question:answer format. There is a game people sometimes play on Reddit where they do this deliberately for humour, but to a lesser extent that happens any time people make significant edits to their posts.
Hypothetical example:
Homer asks “What’s wrong with my code? mylist = [45, 2, 6]; x = mylist.sorted() but x isn’t sorted in order.”
Bart replies: “Sorry, your code isn’t working for me, I get an AttributeError. If I fix it to use sort it works fine.”
Homer then silently edits his question instead of replying, changing the code to mylist = ['45', '2', '6']; x = sorted(mylist). Then Lisa gives him the answer to the edited question, and looks like a helpful and clever fellow, and poor Bart looks incompetent.
In a perfect world we could trust people to only edit their posts to fix minor typos and other inconsequential mistakes, and not to change the semantics of their posts.
Its not a great tragedy when this happens, but it is quite frustrating and annoying.
I do much the same as Cameron, even down to using mutt
So I also see correctly indented code in the text part of the emails sent out by Discuss. But there are other issues.
At times, Discuss seems to insert blank lines between every line. Other times, it seems to put extraneous ^M characters (carriage returns). On occassions it has mysteriously truncated my posts.
(It seems to truncate posts just before a line containing more than two dashes in a row, even if it is protected by code fences or indented, although I cannot reliably reproduce that. It also truncates at Markdown horizontal rules, which is a line of dashes on its own.)
I have seen the curly quotes thing, but I don’t remember the circumstances. Generally they seem to be okay.
I think that posting from the web interface converts straight quotes to curly quotes, but posting from email does not.
Here is an experiment, from email:
Straight quotes, no code fences.
a = ‘Hello world.’
b = “Elvis has left the building.”
Straight quotes, indented code block:
c = 'Spam spam spam and eggs with grated spam.'
d = "Ethel the aardvark goes quantity surveying."
Straight quotes, code fences:
e = 'a b c d'
f = "e f g h"
And inline: g = 'a' + "b".
If somebody cares enough to do the same sort of thing from the web UI, we might be able to determine what is actually happening.
(If I can remember my login details, I may do so myself.)
Even from email, the straight quotes were converted to curly quotes (single: U+2018 and U+2019, double: U+201C and U+201D) when not protected by code fences or indent.
It seems likely that the same will happen from the web UI, but we might as well confirm it with a test.
Straight quotes, no code fences.
a = ‘Hello world.’
b = “Elvis has left the building.”
Straight quotes, indented code block:
c = 'Spam spam spam and eggs with grated spam.'
d = "Ethel the aardvark goes quantity surveying."
I’m not sure there’s a singular authoritative source specifying it as canon, but referring to it as the “Python Discourse [instance]” (or just Discourse for short, within the implied context of it being the Python Discourse instance as opposed to some other one) is, as far as I’m aware, the widely accepted and used name, following the same pattern as, e.g., the Python Discord [server], the Python GitHub [org], the Python IRC [channel], etc. That is also the name I’ve used in the normative PEP 1 and PyPA process documents.
discuss.python.org is just the URL, which perhaps somewhat unfortunately isn’t discourse.python.org, but calling it “Discuss” or “Discussions” is much too generic as opposed to referring to the specific platform, as it could refer to Python discussions in general or on any other platform, and the former is also not a noun, while the latter is neither in the URL, in common use or displayed anywhere prominent.
I’m not sure why they even recommend that at all, when Discourse’s built-in search feature is perfectly functional, as far as I’m aware.
While most other forums have this feature for moderators, I strongly agree that its use should be strictly limited to fixing post formatting only, even by moderators/admins. However, unlike most other forums I’m aware of, I don’t think I’ve ever actually seen it used even once by any admins, moderators, or TL4s.
And unlike most other forums, it is most certainly not silent—a fairly prominent orange edited icon with a count of edits is placed in the top right of any edited post, and clicking on it displays the full history of edits with the diffs of every change and their author and timestamp, which is visible publicly by all. Therefore, if a user does change their OP (and new users have to be TL1, AFAIK, to edit their posts, and they can only do so in a very limited window of time), a quick check of the edit history will show what happened.
Furthermore, there is full transparency as to exactly whether, what and who made changes to any post. If the feature is ever used inappropriately, this will be visible to everyone, and that user/moderator will face appropriate consequences, ranging from TL demotion and being prevented from using that feature again, to being banned.
To further reduce the risk of abuse while increasing the usefulness for the specific purpose of fixing new users’ formatting, if it is possible, TL4 users could be allowed to edit users’ posts up to TL2, TL3 users up to TL1, and TL2 only TL0, such that only mods/admins could edit TL3+, and only the hand-promoted/demoted TL4 (which can currently edit all posts, AFAIK) can edit TL2 users (i.e. most semi-regular users, including you).
This would be a dandy way to help new Discourse users (and ourslves) with their code formatting. The curly quotes would still be in the body text, but a quick drop into an editor and search-replace would handle it. A utility to automatically search and replace the left and right double and single quotes in a plaintext file could also be whipped up quickly.
The email discussion informs us of how big an issue the code formatting is for the mailing list users, so can be regarded as on-topic. Even the post editing analysis, though I’d say it invokes thoughts of “topic scope creep”.
Deconstructing Carol’s post must be declared a separate, subsequent point of discussion if for no other reason than to keep this topic narrow enough to mine for nuggets and design a solution, if a decision is made to move forward.
And here’s my own contribution to the “creep”:
I use discuss.python.org (code formatted to suppress the linking) because discuss.python.org == 'Python Discourse instance' although technically URL(discuss.python.org) ≠ 'Python Discourse instance'
Now back to our regularly-scheduled program…
Regarding viewing a post in plaintext, I just learned about a great tool:
Replace the /t/ in the post URL with /raw/ and strip out the permalink… https://discuss.python.org/t/how-can-i-add-one-value-on-inside-python-file/11704 https://discuss.python.org/raw/11704
…to go from THIS to THIS. It preserves the quotes, indents, contiguous spaces, everything (as far as I can tell). We had a post with a bunch of # comments (with space) that blew into pieces from the huge headers. It was a hot mess and could have benefited greatly from this /raw/ technique. Perhaps Discourse.org would add a button to launch with the /raw URL. I’ll ask. For that matter, it may already be an option and is simply disabled.
Discourse sends messages as 