Just the other day I was on this BBS, and I looked high and low,
but I couldn’t find any Markdown Help button to explain the formatting rules.
No, I’m not asking what the rules are.
Nor am I asking for a link.
I’m saying you need to provide a link to people making a post,
right there next to the textbox, when they are editing it.
Well, OK, maybe any documentation isn’t ready for average users yet,
The composer toolbar has the options in, which would format the text for you and show you how it would work if you wanted to add the Markdown [1] manually. Is this not more helpful than a link that would take you to some documentation outside of the message you’re writing?
and some BBCode depending on what you’re adding ↩︎
Yes. Take the user who wants to say "
not
"
Well, eventually he discovers the correct way to make it look like "
https://www.openstreetmap.org/, not
https://www.openstreetmap.org/edit
".
But there is absolutely no way he could have figured that out if he didn’t have to go figure it out on his own, because, there in the editor, it is a big mystery, with zero documentation. Zero.
I’m saying you need a link like this blue one on GitHub,
You have quite interesting way use a user, he or you everytime you are meaning I. Just saying.
Out there in the Web is three different kind editors when creating content inside a service:
The first group tries to use same logic what office packages teached us even before web. There is no real help-button, because everyone should now what a button does. Or what shortcuts are. And if an user doesn’t know he/she/it have to find that piece of info.
Social media has understood that average Jane and Joe doesn’t need those buttons, because they don’t use those — and on mobiles there is just no room. And there is no help-button, because there is no need for it.
Dev-based ones are offering service to those who know how to mark things without need to see it happening, remember bunch of code and don’t want lift their hands off the keyboard. And there is no help-button, because everyone shall read docs and memorizes how to do tables for example.
But there is different users. On my forum ordinary people are talking about ordinary matters and they have mostly low level tech skills. Here on dev or in GitHub is totally different needs, and assumption is everyone has really high skills. Plus created content is totally different. I’m member on one site where writing itself is in spotlights. There is, again, totally different needs.
The UX-question is not help-button in the toolbox. No one is using it, because it is impossible to create and use. And even a link in github-style is too much. It is totally unrelevant component that is rarely used and everyone knows out there is is docs and manuals.
The real UX/UI-solution is to give ability to
And what the big majority of users actually needs, and what is missing now is a way to hide that toolbar. That would be more important than ablity edit it.
Question of editor is almost FAQ’ish topic here, and a help-button is just part of it. And lets be straight again. Dan has his agenda and help-button is just another sign of it, not the goal. I hope Dan is actually trying to say that he didn’ know how to do a thing and didn’t find help for that. That should be issue of that site, not Disourse as a platform per se.
Yes, I was talking about the real life case where I was posting
and the two link previews were the same, making my post look silly.
So I was battling with the (Discourse) interface, trying to figure out a way to disable
all that magic — with no documentation on how to do it.
So it all had to be trial and error…
Then I experimented with
https://www.openstreetmap.org/ .
https://www.openstreetmap.org/edit .
This gives the odd combination of
https://www.openstreetmap.org/ .
OpenStreetMap .
which, yes, has it’s logic, but that’s not my point.
It is still not what I wanted my post to look like to others.
By this time I thought “I will just look at the official documentation instead of hours of trial and error.”
OK, so I looked and looked and found Supported formatting in posts (markdown, BBCode, and HTML) .
OK, that mentioned the
[url]http://bettercallsaul.com[/url]
format, but with
[url]https://www.openstreetmap.org/[/url]
[url]https://www.openstreetmap.org/edit[/url]
something isn’t working:
[url]https://www.openstreetmap.org/[/url]
[url]https://www.openstreetmap.org/edit[/url]
Therefore Supported formatting in posts (markdown, BBCode, and HTML) is probably out of date, etc.
So how did I finally solve my problem, using
[https://www.openstreetmap.org/](https://www.openstreetmap.org/), not
[https://www.openstreetmap.org/edit](https://www.openstreetmap.org/edit)
to get
https://www.openstreetmap.org/, not
https://www.openstreetmap.org/edit
Well, I remembered you guys use “Markdown”, and I remember Markdown had that syntax,
and it worked.
All
I
am
saying
is
there should be an official document somewhere that tells users what will happen when they type this and that character.
They shouldn’t need to read the source code to find out. Thanks.
Fine, put it in a FAQ, then link the FAQ to the interface somewhere.
OK, let’s say you put the future formatting FAQ on the Discourse website. Problem solved…
except how does the user even know he is using Discourse? Yes I am talking about users, not admins. Thanks again.
Just as an FYI, but there’s this button in the composer that can help out:
If you put the URL in the top box, and the display text in the bottom it will format it in the markdown for you. 
This is a strawman. Maybe there’s a few hard-core helpful dev sorts that have the formatting rules memorized and need no documentation, but not all of the non-beginners have all of the formatting rules memorized.
With the different flavors of markdown, BBCode and html supported by different instantiations of Discourse, there is not a manual out there in the docs.
If someone does built a manual for the particular set of valid markup codes on a site, and wants to put a github-style help link on the composer page, as below, how would one accomplish it?
I see that this exists:
