User docs could use an overhaul. [Rant warning: Tiny, and (mostly) constructive rant].

[svein83]

WOW! I'm sorry, but if you don't want users, or if you want new users to give up, then this is a great way to do it.

I was looking for the manual for the plugin and it's main web-ui. Usage info like formatting and keyboard shortcuts.

This info is critical for new users. People who don't search code-repos for key-bindings in source-files for a living (or for fun), will just get confused and pissed-off.

All places where a man-page should exist, there are just links to the Git-wiki, the Git-repo, or the plugin page. All links I find (where users would look), go to one of those 3 pages.

None of those 3 pages actually tell a user anything:

• Plugin page: Links to project-repo, and project-wiki on GitHub.
• Wiki page:
  Just a list of 3 apps on several app-stores, and some API-info for devs.
• Repo page: A long page with requirements, and a short paragraph says something about supporting Markdown, some more API info, and telling users to go to the project-wiki for more user and developer info.

So this is actually just a giant, useless, and annoying, circle-jerk of hyperlinks to most users! Nothing about how text is formatted, not what flavor of MD syntax, and Not even a hint at where to find the info.

MD has no "one technical de-facto standard" except John Gruber's own syntax-page, and MD has no real keyboard shortcuts standard specified for for editors.

A user manual has to be available if you want users. If it's just a simple list of named links with short explanations doesn't matter, as long as it takes the guesswork and annoyances away. A faq could be a great way to limit the number of issues submitted too.

[svein83]

Nevermind.

I had a look at the source, and noticed that the text editor is SimpleMDE.

For anyone else looking for this info:

That means the keyboard shortcuts are here: link

And a table with the the supported syntax is here: link

[stefan-niedermann]

Thank you for your feedback.

Indeed we can improve the documentation. We already talked about how we can tell users, what the app works like.

One of our ideas was a "default note" which contains the documentation - so users do not have to search the github repo at all but see everything they need as soon as they install and open the app.

What do you think about this idea?

We can put some simole Markdown-tricks as headings, lists and so one there, keyboard shortcuts and so on. What else information could be useful for new users according to your opinion? Do you have any further suggestions?

Regards

[svein83]

I'd rather have a help-icon in the web-app. A default note could okay, but could get deleted, and then someone might get stuck looking for info again... Maybe some info on how to sync with PCs on different OSes? What applications can talk to the API out of box? Den tor. 10. mai 2018, 10:21 skrev Niedermann IT-Dienstleistungen < [email protected]>:

…

Thank you for your feedback. Indeed we can improve the documentation. We already talked about how we can tell users, what the app works like. One of our ideas was a "default note" which contains the documentation - so users do not have to search the github repo at all but see everything they need as soon as they install and open the app. What do you think about this idea? We can put some simole Markdown-tricks as headings, lists and so one there, keyboard shortcuts and so on. What else information could be useful for new users according to your opinion? Do you have any further suggestions? Regards — You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub <#196 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AYSiDJpsKERRCsKB3WrKVcoAsRp9XnL9ks5tw_h6gaJpZM4T43qM> .

[jancborchardt]

@svein83 a proposal is at #200 to introduce a formatting popup which will do away with the need for an intro to Markdown formatting, but simply do it for people.