Thanks for the reply.
Let me try to explain more clearly.
The people creating and editing content will mostly be non-technical users. They won’t be Markdown experts. They want to be able to write text that links to a PDF hosted by Contentful. For example, text like “Please read the white paper about this technology”, where the text read the white paper is a standard hypertext link to the PDF.
As far as I can tell, these are the steps a user needs to take to do this:
- Click “Insert media”, then select “Link existing media”.
- In the dialog, search for the PDF and click OK.
- Edit the resulting Markdown syntax to change it from image syntax to standard link syntax, and merge it into the text where they want the link.
The user experience here is poor. For technical people who know Markdown, it’s irritating. For non-technical people, it’s confusing and error-prone.
Problem 1: going against user expectations
A user wants to insert a link, so they will press the chain-link icon in the toolbar. That’s how you insert links: they’re familiar with this button from many other applications. Pressing the chain-link icon brings up the “Insert link” dialog, but this dialog doesn’t let the user search for assets like PDFs. To insert a link using this dialog, the user must know the URL in advance.
After the user presses the chain-link icon, and realises they don’t know the URL to the PDF, what will they do? They might go to the Media section of the Contentful site, search for the PDF there, display the edit page for the PDF asset, and look for the URL. As far as I can tell, the URL is not shown on that page.
What the user “should have done” is press “Insert media” instead of “Add link”, even though they wanted to add a link, not insert media. This is likely to cause frustration.
Problem 2: expecting a user to understand Markdown syntax to recover from problem 1
OK, the user has discovered they can find the URL for a PDF using “Insert media”. This adds Markdown to the content. The Markdown syntax is for an image, not a simple hypertext link. These two syntaxes are very similar, but not the same.
The user now needs to edit this inserted Markdown to turn it into a standard link, update the link anchor text, and put the link in the right place in the content. Not difficult, but easy to get wrong, especially if the syntax is unfamiliar. If they accidentally remove a square bracket or parenthesis, it breaks. If they accidentally retain the exclamation mark, it’s not going to work.
Being forced to do this because of problem 1 increases the likelihood of errors, as the user is already frustrated.
IMPLICATIONS OF THESE PROBLEMS:
Additional training, as problem 1 means user expectations are not met.
In concrete terms: I’m going to have to stand in front of people and say: “To add a link to a PDF, DO NOT use the ‘add link’ button. Instead, use the ‘insert media’ button, even though you don’t want to insert media, and even though it doesn’t make sense to try to display a PDF as an image anyway. Then remove the exclamation mark from the inserted Markdown, edit the text in square brackets, and copy and paste the entire thing where you want it.”
Additional support, as problem 2 results in content with broken or unexpected Markdown syntax.
Let users search for assets in the chain-link button’s “Insert link” dialog. Both problems go away.
I hope that makes sense.