Update titles under "Getting Started" section

[paigem]

Description

This PR updates the titles in the Getting Started section. I've made some suggestions here, and would like input from the Hive Docs Team on whether these updated titles make sense.

I tried to update the titles in all locations, including the navigation bar and homepage, but please let me know if I missed anywhere.

Fixes #716

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue, e.g. dead links)
• New link / content

Checklist:

• The new content is accessible and located in the appropriate section
• My changes do not break navigation and do not generate new warnings
• I have checked that the links are valid and point to the intended content
• I have checked my code/text and corrected any misspellings
• I have chosen the correct tag for the level of support provided

[atteggiani]

I think overall we can improve many sections' titles and how we structure/frame each of the sessions.
So, thank you @paigem for opening this PR and starting this conversation!

For the specific changes please see the comments under each of those.

Note on the PR and the GitHub actions:

• You started this PR from your fork of this repo, instead of creating a branch directly inside the repo. Is there any specific reason why you chose this approach? In general this is completely fine (and is the recommended approach for an external person that wants to contribute directly) but since you are a member of ACCESS-NRI it might be easier to just create your own branch within the repo itself.
• The Deploy to GitHub Pages action for this PR failed (deployment and PR comment). I am not completely sure why yet, but I guess it has to do with GITHUB_TOKEN permission within the GitHub workflow (most likely because you started the PR from a fork). This of course has nothing to do with you and it's something we need to fix so it doesn't happen for external people. I rasied an issue and I'll have a look into that.
• You opened the PR to be merged into ACCESS-NRI:main, but the correct branch for merging PRs is ACCESS-NRI:developent. You might have followed the Contribute on GitHub guide on the Hive Docs and, in fact, I checked but there is no mention of which branch to select when opening PRs.
  I changed the target branch from ACCESS-NRI:main to ACCESS-NRI:development and I raised an issue to update the instructions on the Hive Docs.

Thank you!!

[paigem]

Thanks @atteggiani for your review! I have a few responses below and have also commented directly on your suggested edits.

1. Good question - if I am making minor updates, then I tend to just create a new branch directly, but if I'm making more significant changes I usually end up pushing from my own fork so I can preview changes locally. Plus, I find it a bit more straightforward to do it this way when I'm making updates to several different files (but that's likely just because it's what I'm used to!). I probably didn't need to do that this time around, but since I was changing wording in the table of contents, I thought it was best if I preview my changes before pushing. Let me know if you'd prefer I just create a branch within the main repo next time.
2. Hmm, there's certainly a chance that I messed something up in my local copy. Let me know if there's something I should fix, or if I should redo the PR from a branch instead.
3. I actually had this question when submitting the PR, but opted to continue instead of reaching out to ask. I did indeed look at the instructions in the contributor guide, and saw that it didn't mention which branch. If you've updated the target branch, then that's great, and thanks for raising an issue to update the guide. 😊

[atteggiani]

Thanks @atteggiani for your review! I have a few responses below and have also commented directly on your suggested edits.

1. Good question - if I am making minor updates, then I tend to just create a new branch directly, but if I'm making more significant changes I usually end up pushing from my own fork so I can preview changes locally. Plus, I find it a bit more straightforward to do it this way when I'm making updates to several different files (but that's likely just because it's what I'm used to!). I probably didn't need to do that this time around, but since I was changing wording in the table of contents, I thought it was best if I preview my changes before pushing. Let me know if you'd prefer I just create a branch within the main repo next time.

That is completely fine and if you are used to that workflow I think there shouldn't be any problems.
However, if you consider to add your changes to a branch of a cloned repo instead (in the future), just two notes:

• For the "preview changes locally" part, you can do that in the same way you would for a forked repo. The recommended way to preview your work is to use mkdocs serve as illustrated in Deploying Website Preview.
• For a cloned repo, it would be a bit easier and linear to keep it updated with the remote repo. However, you can do that even with a forked repo, more details at point 3.

2. Hmm, there's certainly a chance that I messed something up in my local copy. Let me know if there's something I should fix, or if I should redo the PR from a branch instead.

No I am pretty confident this is not your fault. It might be related to your PR coming from an external fork instead of an internal branch, but I still do not know why that happens. In any case, this should NOT happen, and will have to be fixed within the deployment workflow. This PR is perfectly fine.

3. I actually had this question when submitting the PR, but opted to continue instead of reaching out to ask. I did indeed look at the instructions in the contributor guide, and saw that it didn't mention which branch. If you've updated the target branch, then that's great, and thanks for raising an issue to update the guide. 😊

Yeah, no problem!
The only other thing you might need, is to get your feature branch (in your case the paigem:main) up to date with ACCESS-NRI:development.
This is in general a step you should always do to make sure that your feature branch is updated with the default branch for the Hive Docs repo which is development.
This step would be easier and more commonly done for a cloned repo, but can be achieved also for a forked repo.
More instructions are listed in Syncing a fork but, in general, you would have to do something along the lines of:

git fetch upstream -Pp
git checkout <your-feature-branch>
git rebase upstream/development # you can also use 'git merge' but I prefer 'git reabase' 
# You might need to resolve conflicts generated by the rebase/merge
git push

[paigem]

Based on our discussion during our meeting, we can use the phrase "New ACCESS user?"

We should also add a sentence or two on the "Getting Started" page to add a bit of text around what is needed for new ACCESS users.

[flicj191]

Thanks @paigem, I'll approve and merge once those couple things are done

Discussed in meeting 20th August 2024