Page MenuHomePhabricator

The help "Remarkup reference" is unclear and has problems
Closed, InvalidPublic

Description

In Phab, for writing, we have a button Help. This button brings the help "Remarkup reference": https://secure.phabricator.com/book/phabricator/article/remarkup/

This help has many problems.

In this help, some things are very unclear and confusing.

There are some examples with codes and results.

But then, from "Make code blocks by indenting two spaces", things get confused. Where are the codes? Where are the results? The codes and results are often missing, misleading, incorrect.

In the example for "two spaces", there are no "two spaces". This example probably does not work.

In the following example, where are the backticks? I cannot guess how I am supposed to "enclose" the code block in "three backticks". This example probably does not work.

The following example seems incorrect. There is the "lang", so it seems to be code and not result, but there are no "two spaces", no "three backticks". ???

Then, the "COUNTEREXAMPLE" thing is weird. First, the code has no "two spaces", no "three backticks". This example probably does not work. Then, in the result, I just see a code block, I do not see anything "to show that a block of code is bad and shouldn't be copied". ?

Then, an example says: "this: […] produces this […]" This is probably false. In the code, there are no "two spaces", no "three backticks". And not any fruit.

In the part Keystrokes, the "+" between the keys are misleading. This problem may be deeper than in the help.

There are Absurd Capital Letters. Observed "Basic Styling", expected "Basic styling", observed "Quoting Text", expected "Quoting text", and so on.

In the grey code examples, the presentation is very much misleading. For example, I see the code " > This is quoted text." with a space in the code before the ">". In fact, there is no such space, but the grey presentation, with the big grey margin, makes us see such space in the code.

It would be nice to improve and to correct all of that, and to give clear examples with codes AND results.

Thank you.

Event Timeline

Nnemo created this task.Oct 22 2016, 10:53 PM
Restricted Application added subscribers: TerraCodes, Aklapper. · View Herald TranscriptOct 22 2016, 10:53 PM
Aklapper closed this task as Invalid.EditedOct 23 2016, 5:23 PM

But then, from "Make code blocks by indenting two spaces", things get confused. Where are the codes? Where are the results?

Both the random programming/math code example and the result is shown here right under the line that you quoted, in a grey block.
I wonder if you might get confused by the terms "code" and "markup" which are two very different things? :)

In the example for "two spaces", there are no "two spaces".

Likely because the text is considered sufficient and because the upstream maintainers do not see much additional use in showing you how two spaces at the beginning of a line look like. Or three backticks.

This example probably does not work.

It does - test it. :)

Though we link to the upstream help (by default in the user interface and also from our help), Wikimedia does not control content on 3rd party pages such as secure.phabricator.com so if there are really mistakes (which I doubt), input needs to be provided to the upstream developers and maintainers of phabricator.com.

Closing this task as invalid as it's out of scope for Wikimedia (and as I do not see a real problem in not showing an example how two spaces or three backticks look like).