920205 - Shell prompt inclusion is inconsistent, and very confusing.

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: General, defect)

Description

[Mike Hoye [:mhoye]]

Including "$" at the beginning of user-must-type-this shell instructions - a common unixy convention - is used very inconsistently across MDN documentation and is quite frustrating for anyone who doesn't know about it.

Compare:

https://developer.mozilla.org/en-US/docs/Developer_Guide/Source_Code/Mercurial

and

https://developer.mozilla.org/en-US/docs/Windows_8

for example, where a user can copy and paste the entire line in one, but not the other.

For new contributors who are not familiar with using the shell - many new Mac contributors, and virtually all Windows contributors - that convention is a frustrating one that isn't documented anywhere. You can copy-and-paste some commands, but not others, and why they work or not is basically magic; having interviewed a handful of aspiring participants with Windows boxes, this is either a minor annoyance or a straight up roadblock, depending on whether or not they happen to have a veteran Unix user close by to ask when they hit that wall.

We should not include the "$" shell prompt itself in any of our MDN sample code.

Comment 1

[Benjamin Smedberg]

Hrm. Can we use CSS magic (:before) to make a $ visible but not selectable?

Comment 2

[Mike Hoye [:mhoye]]

(In reply to Benjamin Smedberg  [:bsmedberg] from comment #1)
> Hrm. Can we use CSS magic (:before) to make a $ visible but not selectable?

According to this:  

https://developer.mozilla.org/en-US/docs/Web/CSS/user-select?redirectlocale=en-US&redirectslug=CSS/user-select


you can declare text non-selectable with CSS (which surprises the hell out of me, but there it is.) However, I strongly suspect that will lead to more confusion, not less.

Comment 3

[Florian Scholz (Open Web Docs)]

I fixed the Windows 8 article.

This is now mentioned as a guideline in the MDN meta docs https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Code_samples#Shell_prompts

I have opened an issue (https://github.com/Elchi3/mdn-doc-tests/issues/90), so that we can test this with https://addons.mozilla.org/en-US/firefox/addon/mdn-documentation-tester in the future.

I going to close this. Bugs in the lieu of "Fix all the MDN because X is bad" are not really actionable unless there is a precise list of affected docs.