I rarely link to the MRE page to an experienced programmer (even if that happens from time to time), so I think it's important that the page is as concise and simple as possible. Shortening it will also encourage people to read it through as longer texts require a larger time investment and might turn some people away. Of course, important information shouldn't be sacrificed for brevity.
I'll quote some of the text I think is problematic and suggest fixes as best as I can.
"This is referred to by community members as creating a minimal, reproducible example (reprex), a minimal, complete and verifiable example (mcve), or a minimal, workable example (mwe)"
These different names just take up much unnecessary space. It is rarely important to know the different linguistics community members are using, especially when all [mcve] comments are translated to [mre] anyway. What's important is how you create a good example.
My suggestion would be to change this to:
This is referred to as creating a minimal, reproducible example. Other names may occur (see footnote).
This seems reasonable as there is already a footnote explaining different terms used.
"Regardless of how it's communicated to you, it boils down to ensuring your code that reproduces the problem follows the following guidelines:"
This is just unnecessary noise... My suggestion:
This is to ensure your code is following the guidelines:
The bullet-point summary is quite good:
- …Minimal – Use as little code as possible that still produces the same problem
- …Complete – Provide all parts someone else needs to reproduce your problem in the question itself
- …Reproducible – Test the code you're about to provide to make sure it reproduces the problem
My only problems are that the dots before each word seem out of place. It looks unconventional and doesn't provide anything. Also, I think "Test" should be in bold.
"The rest of this help article provides guidance on these aspects of writing a minimal, reproducible example"
You don't need to say what's coming next. It's obvious from the titles. Remove this sentence completely.
"The more code there is to go through, the less likely people can find your problem"
This is one of two times where I think we should elaborate more. The sentence makes it seem that the problem is solely that the user might not get an answer when it is in fact a way for the answerers to not have to go through hundreds of lines of code. That should be emphasized.
Maybe something in line with:
The more code there is to go through, the more time it takes users to find your problem and the less likely they are to find it.
"Use simple, descriptive names for functions and variables – don’t copy the names you’re using in your existing code"
This is misguiding. I think it's okay to use names from existing code, as long they're simple and descriptive names. So much of this is redundant. You just need to have:
Use simple, descriptive names for functions and variables.
"Also, use spaces instead of tabs – tabs might not get correctly formatted on Stack Overflow"
Is this still necessary? I always use tabs and SO should handle this properly by now. I'd suggest removing it and fixing any problems that may occur from not including this line on the page.
"If the problem requires some server-side code as well as some XML-based configuration, include code for both. If a web page problem requires HTML, some JavaScript, and a stylesheet, include code for all three."
This example is way too complicated and specialized for someone who doesn't know how to write an MRE. My suggestion would be something along these lines:
If the problem requires both code and a file, include both the code and the contents of the file. And if it involves an image also, then include it as well.
"Use Stack Snippets to include runnable HTML, JavaScript, or CSS."
This is only for javascript and is not necessary for a huge majority of people. Most users write in different languages and even the people who write in Javascript might not have enough for Stack snippets to be applicable since they are using a backend. I'd suggest removing this completely or, as suggested in the comment section, recommend checking the language-specific tag for language-specific steps to post code.
"This helps others more easily read and test your code."
This is the second time I'd argue for more elaboration. Images in code have more problems than this. It might not be necessary to list them all here, but something like this would be nice:
This helps others more easily read and test your code, and helps with many other problems.
"Instead, tell other readers what the expected behavior should be. Tell other readers what the exact wording of the error message is, and which line of code is producing it."
A small change, but replace this with a comma.
Instead, tell other readers what the expected behavior should be, what the exact wording of the error message is, and which line of code is producing it.
"If your question isn’t about a compiler error, ensure that there are no compile-time errors."
Remove the mention of a compiler. It makes it easier for people who don't know what a compiler is, and an error can exist without it being a compile error. It'll make sense either way without the risk of confusion.
"Use a program such as JSLint to validate interpreted languages. Validate any HTML or XML."
Again with web programming. This is not a majority of the users. Be more general.
"If you inadvertently fixed the problem while composing the example but didn't test it again, you'd want to know that before asking someone else to help."
I think this is could be simplified by just saying:
Always test your code before posting to verify it still exhibits the same problem you're asking about.
These are some suggestions I think would greatly improve the MRE page.
[mre]
and[mcve]
tags.[mre]
shortcut, perhaps adding a note to the MRE help page would be useful?idownvotedbecau.se
site, maybe link to this FAQ? Also “JSLint” → “linters”, and remove “interpreted”…