search

openstreetmap / openstreetmap-website

The Rails application that powers OpenStreetMap
https://www.openstreetmap.org/
GNU General Public License v2.0
2.2k stars 910 forks source link

Improve markdown guide language #3967

Open willemarcel opened 1 year ago

willemarcel commented 1 year ago

Problem

The markdown reference in the New Diary page is not very friendly.

image

Probably many users don't know what "Parsed with kramdown" means

Description

We could improve the language, doing something like: image

Screenshots

No response

AntonKhorev commented 1 year ago

Probably many users don't know what "Parsed with kramdown" means

That's why there's a link. Do you want to hide the fact that it's kramdown and not some other markdown dialect? Do you want to link to the complete kramdown syntax reference as opposed to the quick reference?

willemarcel commented 1 year ago

@AntonKhorev it can be the quick reference link. My problem with "Parsed with kramdown" is because it's too technical for users that are not software developers.

AntonKhorev commented 1 year ago

My problem with "Parsed with kramdown" is because it's too technical for users that are not software developers.

Do you think that "Parsed" is too technical or is it "kramdown" or both?

AntonKhorev commented 1 year ago

Translations of "Parsed with kramdown" are now broken by the way. Maybe they are not yet updated after recent changes to https://github.com/openstreetmap/openstreetmap-website/blob/master/app/views/shared/_markdown_help.html.erb

AntonKhorev commented 1 year ago

You can say that "parsed" is wrong because it's shown before anything is parsed. You can write instead "Styling with kramdown is supported" like Github does.

SomeoneElseOSM commented 1 year ago

Do you think that "Parsed" is too technical or is it "kramdown" or both?

Both.

Better instead would be "you can use Markdown here", perhaps hotlinked to an example of the things that you can do. https://daringfireball.net/projects/markdown/ is a reasonable summary; https://kramdown.gettalong.org/documentation.html is not.

AntonKhorev commented 1 year ago

https://kramdown.gettalong.org/documentation.html is not a summary, the current link is.

SomeoneElseOSM commented 1 year ago

https://kramdown.gettalong.org/documentation.html is not a summary, the current link is.

For completeness, that's to https://kramdown.gettalong.org/quickref.html and it's still a bit complicated. Wille's suggestion at https://github.com/openstreetmap/openstreetmap-website/issues/3967#issue-1619446106 would be an improvement on that.

AntonKhorev commented 1 year ago

Wille's suggestion at #3967 (comment) would be an improvement on that.

But this suggestion has "Complete markdown reference" for a link and you don't want a complete reference.