1726962 - Improve Markdown Help link and discoverability of Bugzilla Tips

Status: UNCONFIRMED

(bugzilla.mozilla.org :: Bug Creation/Editing, enhancement, P5)

Description

[tero gusto]

User Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:91.0) Gecko/20100101 Firefox/91.0

Steps to reproduce:

While investigating markdown support in forms, I found bug 40896 and bug 330707 and noticed the smart links, for example with strike-through if closed. That's a great feature!

I now understand that the syntax "bug #####" is converted into a link automatically ("linkified") which is not listed in the standard markdown documentation page at github.com for obvious reasons, but quite useful.

Perhaps it could it be added right after the link to the "Markdown styling now supported" link, like this?

Markdown styling now supported (bug #### is automatically linkified)

Comment 1

[Robert Longson [:longsonr]]

bug #### was linkified by bugzilla long before markdown support was added. It's described here: https://www.bugzilla.org/docs/2.18/html/hintsandtips.html

Comment 2

[tero gusto]

Thanks for directing me to the documentation Robert.

My point was merely that there is a link below the form to a page about formatting. We could consider adding a tip about the great linkification feature there as well, since it is not mentioned on that page, because it is not Bugzilla specific. Does that make sense?

While creating the issue, I was not doubting that linkification was documented somewhere. But how is a new Bugzilla user supposed to look for something, if the user doesn't even know it exists?

My reason for creating this issue is to make it easier to on-ramp new users, so perhaps a link to the Bugzilla Hints and Tips docs could be added, to supplement the markdown docs link? Something like this:

Markdown styling now supported | Bugzilla Hints and Tips

That would certainly have helped.

Comment 3

[tero gusto]

It's probably better to use the link pointing to the latest version, since it is not version specific:

Markdown styling now supported | Bugzilla Hints and Tips

Comment 4

[:glob ✱]

We shouldn't link to https://bugzilla.readthedocs.io/en/latest/using/tips.html; the version of Bugzilla that BMO runs is extremely different from upstream.

We should instead link to https://bmo.readthedocs.io/en/latest/using/tips.html after updating it to add markdown and all the additional things BMO supports (eg. linking to crash-stats, CVE/CAN, GitHub PRs and comments, hgmo, etc).

When this is fixed it's probably a good time to change "Markdown styling is now supported" to just "Markdown Help".

Comment 5

[tero gusto]

(In reply to :glob 🎈 from comment #4)

We should instead link to https://bmo.readthedocs.io/en/latest/using/tips.html after updating it to add markdown and all the additional things BMO supports (eg. linking to crash-stats, CVE/CAN, GitHub PRs and comments, hgmo, etc).

When this is fixed it's probably a good time to change "Markdown styling is now supported" to just "Markdown Help".

Thanks for clarifying. If I understand it correctly, markdown details will be added to the Bugzilla docs. Until it's ready, this would be an improvement:

Markdown Help | Bugzilla Tips