Page MenuHomePhabricator

Additional remarkup assistance buttons for decriptions
Closed, WontfixPublic


The remarkup assist bar already has some useful buttons for text formatting, lists or uploads. Our problem is that most of our users don't know the remarkup syntax. They only use the provided functions in the assist bar. Some of the remarkup formattings can only be used by users who know the remarky syntax.

Is is possible to add buttons to the assist bar for elements like the different notes (note, important, warning, error), checkboxes or counterexamples for code?

Event Timeline

In general, we can't possibly create buttons for everything -- there are way too many rules, and some of the rules don't lend themselves easily to clicking a button. The icon already links to the full documentation, which explains everything (and this document is huge, because there are ton of rules).

Can you explain what specific problems you're experiencing in more detail (see Describing Root Problems)? For example, why is it an issue if users don't know how to use WARNING?

The expectation is that:

  • it's OK if not all users are masters of formatting things; and
  • if users see an element they want to use, they can easily figure out how to recreate it (by examining the raw text, or clicking the "Help" icon to go to the documentation).

Are you experiencing something different (some need for users to master remarkup immediately, or difficulty figuring out how to reproduce an element)?

We use a custom field release description of type remarkup. We then export tasks via conduit API to our HTML release notes. In this release description we use some of the remarkup feature set.

I would roughly distinguish between two types of users on our Phabricator system. The technical users have no problem using markup code directly and to look up the right commands. The non-technical users only use the editor with the provided functions via the buttons.
We want to enable both groups to use the same feature set for our descriptions.

Additionally it hard to remember the right code word for each element. So in trying out to make a blue info box the first attempt is to write INFO and not NOTE. Or to make a red box for important stuff, the first guess would be to use the ERROR label. To find the right wording we then end up looking it up to find out it is IMPORTANT.
Also most of our users are only german speaking which makes it even harder for them to use the correct english words.

It would be great to have the option to configure the available buttons for the remarkup editor, so that we can define which feature set we want to provide for the users. For example we don't use tables and memes, but we use the different elements to call attention to an important idea like note, important and warning.

In the end it would make the use of the editor more comfortable. If the relevant features are provided via buttons, there is no need to look features up in the help documentation each time. New and irregular users would profit to use the feature set as provided and don't necessarily have to learn remarkup.

chad claimed this task.
chad added a subscriber: chad.

I don't see anything here worth moving forward. I don't think the bar needs to cover more advanced topics and more advanced users should be OK with reading documentation.