Update for Ubuntu Mantic

[hippytaffer]

No description provided.

[k-dimple]

Hello @hippytaffer, thanks for giving this a go! It needs some more work though, so could you try the following?

1. Run spell check on the project and try to ensure that there are no spelling mistakes, e.g. Mantic has been misspelt as Mantis, cick instead of 'click'. These contribution guidelines might help.
2. The idea was to use all the instructions from the discourse post as is, but write it in the format of the existing how-to guide. So for instance, we can no longer use TightVNC and it's related instructions. Sorry about not fleshing out enough details in the issue description!
3. Also the capitalisation of words seems to be off. If you are using capitalisation to indicate a specific UI element, you can highlight that using :guilabel:. You should find a similar example (Connect!) in the last line of the guide.
4. Try to avoid add specific non-mandatory instructions such as "Name your instance Ubuntu Mantic". Since this is how-to guide and not a tutorial, we assume that the reader is relatively comfortable with the steps that have to be performed in a normal use case. So even if naming the instance happens to be a required step, we can always let the user choose a suitable name.

Also, just out of curiosity, did you try out some of these things on your own and write instructions based on that or were you using the discourse post as a baseline?

[hippytaffer]

Hi, Thanks for this. I’ll continue to work on the document as specified. I did try out the first part of the instructions (The AWS bit) as I wrote them. However, I didn’t realise the rest of the document needed updating too. I will crack on with this and try and learn to spell. Thanks for the feedback and clarification. Much appreciated!

…

On Thu, 14 Mar 2024 at 09:34, Dimple Kuriakose ***@***.***> wrote: Hello @hippytaffer <https://github.com/hippytaffer>, thanks for giving this a go! It needs some more work though, so could you try the following? 1. Run spell check on the project and try to ensure that there are no spelling mistakes, e.g. Mantic has been misspelt as Mantis, cick instead of 'click'. These contribution guidelines <https://canonical-aws.readthedocs-hosted.com/en/latest/aws-how-to/contribute-to-these-docs/#new-content> might help. 2. The idea was to use all the instructions from the discourse post as is, but write it in the format of the existing how-to guide. So for instance, we can no longer use TightVNC and it's related instructions. Sorry about not fleshing out enough details in the issue description! 3. Also the capitalisation of words seems to be off. If you are using capitalisation to indicate a specific UI element, you can highlight that using :guilabel:. You should find a similar example (Connect!) in the last line of the guide. 4. Try to avoid add specific non-mandatory instructions such as "Name your instance Ubuntu Mantic". Since this is how-to guide and not a tutorial, we assume that the reader is relatively comfortable with the steps that have to be performed in a normal use case. So even if naming the instance happens to be a required step, we can always let the user choose a suitable name. Also, just out of curiosity, did you try out some of these things on your own and write instructions based on that or were you using the discourse post as a baseline? — Reply to this email directly, view it on GitHub <#190 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AOJSA3OZKGI5CVIGYPXDFGLYYFVJJAVCNFSM6AAAAABEUD7MCCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOJXGAZDCMJWHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[k-dimple]

Most welcome! And do let me know if you have any questions as you go about doing it.

[hippytaffer]

Hi Dimple, Just a quick question, does the document need to use remmina or just the reader's "favorite RDP client" as in the article?

…

On Thu, 14 Mar 2024 at 10:21, Dimple Kuriakose ***@***.***> wrote: Most welcome! And do let me know if you have any questions as you go about doing it. — Reply to this email directly, view it on GitHub <#190 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AOJSA3LILF3QJK65TUZMLK3YYF22VAVCNFSM6AAAAABEUD7MCCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOJXGEYDQOJVGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[hippytaffer]

Hi again, I've submitted another 'first draft' pull request. Would you mind looking over it for formatting and style? Is it too unfriendly/impersonal? I think I'm sticking to the diataxi-city but I'm not sure if it's a bit too 'to the point'. Thanks On Thu, 14 Mar 2024 at 20:08, Gareth Williams < ***@***.***> wrote:

…

Hi Dimple, Just a quick question, does the document need to use remmina or just the reader's "favorite RDP client" as in the article? On Thu, 14 Mar 2024 at 10:21, Dimple Kuriakose ***@***.***> wrote: > Most welcome! And do let me know if you have any questions as you go > about doing it. > > — > Reply to this email directly, view it on GitHub > <#190 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AOJSA3LILF3QJK65TUZMLK3YYF22VAVCNFSM6AAAAABEUD7MCCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOJXGEYDQOJVGI> > . > You are receiving this because you were mentioned.Message ID: > ***@***.***> >

[k-dimple]

Hi @hippytaffer, sorry about the delay in responding (haven't been feeling too great). It'll take me some time to catch up and get to your PR. Please bear with me till then.

Meanwhile one quick comment - are you using a local set-up to test your changes before pushing updates to the PR? If not, you should definitely try that using the contribution guidelines that I had mentioned earlier - it's usually an easier workflow and we can avoid unnecessary commits. Also, it'll be good if you could squash all your commits and create a single one so that we can have a cleaner history that is easy to understand later. Do let me know if you have any questions or face any issues.

[hippytaffer]

Hi Dimple, Sorry to hear you’re not feeling too great. Hope you feel better soon. I usually have a local set up when I’m using git for other projects, but I have been lazy and have been using GitHub for this. I will continue locally, makes sense to keep the commit history cleaner. Thanks for the feedback and advice.

…

On Mon, 18 Mar 2024 at 07:49, Dimple Kuriakose ***@***.***> wrote: Hi @hippytaffer <https://github.com/hippytaffer>, sorry about the delay in responding (haven't been feeling too great). It'll take me some time to catch up and get to your PR. Please bear with me till then. Meanwhile one quick comment - are you using a local set-up to test your changes before pushing updates to the PR? If not, you should definitely try that using the contribution guidelines <https://canonical-aws.readthedocs-hosted.com/en/latest/aws-how-to/contribute-to-these-docs/#new-content>that I had mentioned earlier - it's usually an easier workflow and we can avoid unnecessary commits. Also, it'll be good if you could squash all your commits and create a single one so that we can have a cleaner history that is easy to understand later. Do let me know if you have any questions or face any issues. — Reply to this email directly, view it on GitHub <#190 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AOJSA3JRRUVXTU5F6AI3DADYY2MCJAVCNFSM6AAAAABEUD7MCCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAMBTGEZDINRWGU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[k-dimple]

Hi @hippytaffer, extremely sorry about the long delay in getting back to you on this. As you'll see from the comments, it needed some detailed consideration and I finally got the time to get into it today (it being a public holiday for me)!

Do take a look and let me know if you have further questions. In general, as a first attempt let's try to stick to the main content from the discourse post and if possible try out the steps to ensure that it works. (Since it is a recent post, most probably it should work fine.)

I realise that referring to this task as updating an existing page is kind of misleading and probably created some confusion. Sorry about that!

Also, to answer your question regarding the tone (whether it is too unfriendly/impersonal), I think it is fine. Since it is a how-to guide, it's better to be 'to the point'. We are helping someone to get their work done, not teaching them something (tutorial) or giving them some explanations for light reading.

[k-dimple]

Let's change this to 'Launch an Ubuntu Mantic desktop on EC2'. We want to try and minimise the number of words used, while still conveying things accurately. We want the title to include important words to help with SEO, but at the same time we don't want it to be too long or unwieldy to read.

Such decisions are quite subjective, but that's okay since the whole documentation process is quite iterative and we'll keep improving things in the future.

[k-dimple]

This start sounds a little too much like an instruction rather than an introduction. The whole how-to guide is basically a set of instructions, but it is usually nice to have an introductory statement before the actual steps begin. It could be something along the lines of what we are trying to achieve and an overview of how we are going to do that. Your statement is exactly that, but could you try to make it sound less like an instruction? Also you missed the 'Mantis' :)

[k-dimple]

The description in this section & in the next section needs to be more detailed, especially because there are quite a few screen changes happening during the process. Although we assume that the reader is familiar with the system, while giving instructions we still have to ensure that all steps are mentioned (as precisely as possible) and there is minimum room for confusion. So we need to stick to a specific flow and mention options/choices as and when required within the flow.

We can use screenshots if something is not obvious or is difficult to find, but in general we prefer to minimise their use.

[k-dimple]

• Include the link for the search as in the discourse post, it helps.
• Don't capitalise unless required. It could be required in some cases such as if it is a brand name or if we are referring to an UI element. But if its an UI element, then we also use its appropriate formatting. So e.g. if it's a button use :guilabel: along with the exact wording of the button.

[k-dimple]

"Select a region closest to you" sounds like a requirement, which it is not. They could ideally select any region that they want. So we try to avoid such suggestions in how-to guides where the user is expected to have some prior experience with the system and can independently take basic decisions. On the other hand, such a suggestion would be ideal in the case of a tutorial.

typo: 'exapmple'

[k-dimple]

Use sentence case for all titles. This style guide might be helpful in such instances.

[k-dimple]

Add some statement like - "Install Ubuntu Desktop and the Snap Store:"

[k-dimple]

typo: succseful (Run PROJECT=aws make spelling on your local instance to catch the typos)
It might be a good idea to mention that on successful connection, you only see a vanilla Gnome desktop without the Ubuntu session.

[k-dimple]

typo

[k-dimple]

For this and the following sections: Since we have set up the RDP server, and plan to use that, these sections and references to VNC are not needed. Just use a single consistent approach as mentioned in the discourse post.

[rpocase]

Thanks for all the improvements! My only major concern is this is pointing to a non-lts release. We should either update this to use jammy OR fast follow with updating this to use noble (post release)

[k-dimple]

@rpocase yes, that is a very valid concern. Thanks for pointing it out! Hopefully the process won't change too much for noble. So we'll work on getting this content right and then update it to noble (post-release).

[rpocase]

with the noble release today can we go ahead and update the content to use Noble (24.04) instead of Mantic?