16

Visiting the How to create a Minimal, Complete, and Verifiable example page, I found there is a tiny footnote that is almost impossible to read (or maybe my eyesight is failing me):

footnote on mcve page

Quote for reference:

You may have been told to include a MCVE by some helpful commentatory, or perhaps even an MVCE if they were rushed; sorry for the initialisms, this is what they were referring to.

I feel like one of these two things should happen:

  • The text should be bigger: right now it is too small to be read/accessible; or
  • The text should be removed: that footnote doesn't really improve or make that article any better.
3
  • 15
    I can honestly say I never spotted that before.
    – Jongware
    Commented Jan 29, 2016 at 18:24
  • 6
    @Jongware it is not there to be spotted, it is there so that page can be found...
    – rene
    Commented Jan 29, 2016 at 19:09
  • 8
    Incidentally, I'm pretty sure "commentatory" is not a real word...
    – IMSoP
    Commented Feb 1, 2016 at 11:21

3 Answers 3

7

As other commenters have said, if it exists to aid searchability, it should be in the main text. If I'm searching for "MCVE", and I see that in the search results, I could still be none the wiser as to what it means. The title does not make it particularly obvious - "Minimal, Complete and Verifiable example" would give you either "MCAVE" or "MCV", and the term is never mentioned in the text.

Why not reword to something that introduces the term; e.g. old:

When asking a question about a problem caused by your code, you will get much better answers if you provide code people can use to reproduce the problem. That code should be…

New:

When asking a question about a problem caused by your code, you will get much better answers if you provide code people can use to reproduce the problem. We call this a "Minimal, Complete, and Verifiable Example", or "MCVE"; that means code that is...

That doesn't cover the typo version, but perhaps a new last sentence, in proper font size, could be added with a few synonyms:

Note that this particular terminology is how we normally refer to these principles on Stack Overflow; you may come upon other terms or acronyms, like "MVCE" or "SSCCE" ("Short, Self Contained, Correct (Compilable), Example"), which are basically all names for the same idea.

That way, rather than trying to game the search engine, we're actually doing what it was intended to do - give people content that matches what they're searching for.

1
  • Ever since I created the bug report that spawned this change I've been wondering what the process is behind getting the help texts updated. Who does it? What are the steps to get it done? Does it need verifying? since the "bug" got fixed through a bug report, I guess you should be able to make this answer a feature request.
    – Gimby
    Commented Feb 1, 2016 at 14:19
37

The text should be removed: that footnote doesn't really improve or make that article any better.

It exists to serve exactly one purpose: letting you search for MCVE or MVCE to find that page.

14
  • 2
    I see now. But wouldn't there be better ways than that? Not trying to be mean, but it looks like it could use some improvement. Commented Jan 29, 2016 at 19:45
  • 5
    The real question is, how much time do I want to spend on improving it? It's a bit of service to folks referencing the page, who... Are not exactly the primary audience for the page.
    – Shog9
    Commented Jan 29, 2016 at 19:46
  • 1
    True. Good point. Commented Jan 29, 2016 at 19:53
  • 4
    Just change the font color to white (just like any other hacked CV containing text that it doesn't) ;) Commented Jan 30, 2016 at 0:15
  • 26
    If the purpose is to make the term "MCVE" findable by a search engine, why not start off the page with How to create a Minimal, Complete, and Verifiable example (MCVE). I believe it is common practice to define an acronym on first use, and then continue using the acronym for the remainder of the text; this proposed change would jibe with that approach and address the searchability issue as well.
    – njuffa
    Commented Jan 30, 2016 at 1:26
  • 1
    @njuffa did you notice "or MVCE" part? Commented Jan 30, 2016 at 1:54
  • 1
    @AlexeiLevenkov "(MCVE, sometimes misspelled MVCE)"? Commented Jan 30, 2016 at 2:25
  • I am not sure it is necessary to include possible misspellings. Is there data that shows people frequently (i.e. high percentage of queries) look for a misspelled variant (mostly transposed letters, I would think)?
    – njuffa
    Commented Jan 30, 2016 at 3:04
  • 1
    But it's not technically a misspelling, only a transposition. "MVCE" conveys exactly the same meaning as "MCVE" or even "CVME" or "VMCE", just in a different order.
    – Scott Odle
    Commented Jan 30, 2016 at 23:35
  • 1
    @AndrasDeak And risk the wrath of the search engines? I don't think so. Commented Feb 1, 2016 at 10:41
  • 5
    "sorry for the initialisms" that phrase. It threw the whole meaning of the sentence for me. Made the whole thing look like a dev note that made it into production.
    – user1228
    Commented Feb 1, 2016 at 15:33
  • 4
    I'm fairly certain that this one sentence has now received more analysis than the entire body of the article. It is the duck.
    – Shog9
    Commented Feb 1, 2016 at 19:51
  • @Shog9: Given that (most of) the info in the footnote now seems to be in the opening paragraph of that Help Center page already, is it safe to remove the footnote now?
    – V2Blast Staff
    Commented Nov 30, 2022 at 20:45
  • 1
    Probably, @V2Blast - been like 7 years
    – Shog9
    Commented Nov 30, 2022 at 20:59
2

There have been a number of changes to this Help Center page since you originally posted this request. This Help Center page is now titled "How to create a Minimal, Reproducible Example". The current URL slug for it is also more descriptive: minimal-reproducible-example (rather than just mcve – which still works, and seems to redirect to the current URL).

The text of the page has also changed in some ways – but I still see (a version of) the footnote you mentioned at the bottom of the page:

You may have been told to include an MCVE – Minimal, Complete, and Verifiable examples is what they were referring to. MCVE was also the former name of the page you're reading now, occasionally misspelled as MVCE, before it was renamed to Minimal, Reproducible Example (sometimes called “reprex”, “min-reprex”, “repro” or just “example”).

According to Shog9's answer, this footnote was originally included for searchability (i.e., so that this page would show up in the Help Center search results for MCVE or MVCE) – and it looks like it was later expanded to include more alternate terms as well.

However, it looks like the opening paragraph now mentions most of the important info from that footnote in a more natural way:

When asking a question, people will be better able to provide help if you provide code that they can easily understand and use to reproduce the problem. 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). Regardless of how it's communicated to you, it boils down to ensuring your code that reproduces the problem follows the following guidelines:

Since this opening paragraph includes the relevant info already, I've gone ahead and removed this redundant footnote from the page.

(I don't think it's particularly necessary to keep alternate spellings like "MVCE" in the page text; there are simpler/more obvious terms you can search the Help Center for if you want to find this page, e.g. "minimal".)

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .