Multipass: improve presentation of links

[rkratky]

Context

Multipass project docs are in a reasonably good shape, but there are (as always) little things that could be improved to offer better user experience. One of them is the way some of the hyperlinks are presented.

The Multipass docs are maintained in and published from the Ubuntu Discourse forum. To suggest changes in a Discourse-hosted docs page, scroll all the way down to the bottom of the page and open the page to which the "Help improve this document in the forum" link points. On the Discourse page, scroll to the bottom of the article (if there are comments, then the bottom of the article is just where the comments start, i.e. not at the very bottom of the page) and click "Edit". (You need an account on Ubuntu Discourse.)

Task

Modify all links in the docs set that use a non-descriptive and user unfriendly link text, such as "here", to use the title of the linked page as their link text. Where needed, adapt the wording of the sentence surrounding the link to reflect the new link text.

Example

Section: Install Multipass Link: "...follow the instructions given here." New link text: "How-to guides" New surrounding text: "...follow the instruction in the How-to guides."

[bagustris]

Hi @rkratky,

I am interested in tackling this issue. However, I cannot find the "Edit" button at the end of the article, although I have already logged in to the discourse.

Here is what I saw at the bottom of the article.

[rkratky]

I am interested in tackling this issue.

Great. I assigned the issue to you.

However, I cannot find the "Edit" button at the end of the article, although I have already logged in to the discourse.

That's an unfortunate feature of Discourse -- it only allows editing for those who have already been participating in the discussion forum. Of course, this is not ideal, but I'm afraid there's no workaround at this point.

I'd suggest -- if OK with you -- editing the Markdown source of the respective pages and then submitting them as stand-alone files through a PR to this repo (similarly to what has been done, for example, here: https://github.com/canonical/open-documentation-academy/tree/main/snapcraft/how-to/java-applications).

We can then do a review in this repo and once done, someone will submit the result to Discourse. Or perhaps you will have gained sufficient rights to edit the Discourse pages yourself by then :) I realize that's not ideal, but it's better than nothing.

[bagustris]

@rkratky

• it only allows editing for those who have already been participating in the discussion forum.

I already participated in one of the discussions, but I still can't edit it.

It is unfortunate since I need to copy-paste the markdown from the discourse, which cannot show a single latest edit (markdown) but two latest edits.

It would be easier if the user assigned here could edit in discourse directly: simpler and faster. Since the edit can be reverted backward through various versions, Canonical members could easily revert it to the previous version if the edit contains something suspicious or out of content.

I did PR with three file edits by searching with the keyword "here" in the Multipass documentation.

[rkratky]

I already participated in one of the discussions, but I still can't edit it.

There's some threshold you need to reach - the system counts the various contributions. That said, when you wish to contribute to docs, we should be able to do some shortcut.

It is unfortunate since I need to copy-paste the markdown from the discourse, which cannot show a single latest edit (markdown) but two latest edits.

To get the latest version in Markdown for any Discourse page, use raw in the URL in place of the post's name. For example, for the page in question, it would be https://discourse.ubuntu.com/raw/28394 (I should've mentioned this before).

It would be easier if the user assigned here could edit in discourse directly: simpler and faster. Since the edit can be reverted backward through various versions, Canonical members could easily revert it to the previous version if the edit contains something suspicious or out of content.

Yes. As I said above, we should be able to fix that. Still, I think it makes sense to use this repo as a "staging ground" -- that way we can do a proper review of the suggested changes, and only then the content is moved to Discourse. (Of course, this is only needed for docs that are in Discourse -- for docs that already are in Git, PRs can go directly to the respective repos).

I did PR with three file edits by searching with the keyword "here" in the Multipass documentation.

Nice, thank you. I'll try to provide a review soon.

[rkratky]

PR: #61.

[giuliazanchi]

Done, thank you @bagustris !