Reorganise documentation - Round 1 #107

dsj976 · 2023-06-19T13:55:27Z

Summary

This is the first round of changes I intend to make while reorganizing content across the three places that REG uses to host its documentation: the Hut23 wiki, the REG wiki and this Handbook.

Related issues and PRs

Contributes to Wiki migration #21
This pull request

Updates

Specifically, I have moved content from the Hut23 and REG wikis to this Handbook. All the information that has been moved is non-confidential, but this should be reviewed.
I have created a new section in the Handbook that I have called "Miscellaneous". This is probably not the best name, but it does actually contain miscellaneous stuff from the Hut23 and REG wikis. As more content is moved to the Handbook, we could think of a better alternative.

Once this PR is merged, I will open equivalent PRs in the REG and Hut23 wikis to remove the relevant content from there so that information is not duplicated across the three sources. More specifically, the content will be replaced with links pointing to the Handbook.

JimMadge

Can we break the pages out into different PRs? It should be easier to review that way.

In general, much of what is here seems out of date, duplicated or incorrect.
I don't see the virtue of merging this into the handbook; it will be misleading for readers and put the burden on someone to correct it later.
I think there needs to be more consideration of what needs to be amended and what should be dropped. We should pull in those that know to help with individual pages.

Not keen on a miscellaneous section.

JimMadge · 2023-06-19T14:42:57Z

content/docs/miscellaneous/acronyms_and_abbreviations.md

+ALOGIT: name of a Fortran package (see [issue](https://github.com/alan-turing-institute/Hut23/issues/295))
+ASG: AI for Science and Government (the new name of the EPSRC funds from SPF)
+
+ARC: Australian Research Council


This probably not the ARC people will encounter the most.

how about:
"ARC: Applied Research Centre / Australian Research Council"

or maybe just:
"ARC: Applied Research Centre"

JimMadge · 2023-06-19T14:43:21Z

content/docs/miscellaneous/acronyms_and_abbreviations.md

+
+AIDA: Artificial Intelligence for Data Analytics
+ALOGIT: name of a Fortran package (see [issue](https://github.com/alan-turing-institute/Hut23/issues/295))
+ASG: AI for Science and Government (the new name of the EPSRC funds from SPF)


ASG has concluded now.

Does that mean it should be removed? It might still be referenced somewhere, and would be useful to know what it stands for

JimMadge · 2023-06-19T14:43:37Z

content/docs/miscellaneous/acronyms_and_abbreviations.md

+# Acronyms and Abbreviations
+
+AIDA: Artificial Intelligence for Data Analytics
+ALOGIT: name of a Fortran package (see [issue](https://github.com/alan-turing-institute/Hut23/issues/295))


This was a small project a number of years ago, I doubt it will come up.

Similar concerns to my comment above... it might still be referenced somewhere, and would be useful to know what it stands for

JimMadge · 2023-06-19T14:44:18Z

content/docs/miscellaneous/acronyms_and_abbreviations.md

+
+LwM: Living with Machines
+
+MRO: ?


We shouldn't include this if we don't know what it is.

JimMadge · 2023-06-19T14:45:07Z

content/docs/miscellaneous/books_and_journal_access.md

+
+## How to be added onto the BL journal access
+
+**Note: this section needs reviewing, might be outdated.**


We should really be clear on this before publishing it.

JimMadge · 2023-06-19T14:45:54Z

content/docs/technical_practices/azure/_index.md

+
+# Azure
+
+Azure is Microsoft's cloud service. The Turing has a grant from Microsoft to use this.


This isn't true now.

JimMadge · 2023-06-19T14:46:34Z

content/docs/technical_practices/azure/_index.md

+# bookSearchExclude = true
+---
+
+# Azure


It is probably better to reference Mathison here which should be the canonical source for using Azure for work.

JimMadge · 2023-06-19T14:48:29Z

content/docs/technical_practices/azure/azure_make_vm_with_cli.md

+# bookSearchExclude = true
+---
+
+# Azure via CLI basic quickstart


I don't think we want to duplicate or compete with Azure documentation, for example.

We are not going to be able to keep this as current or correct as Microsoft.

JimMadge · 2023-06-19T14:49:27Z

content/docs/technical_practices/how_to_use_hub23.md

+# How to use Hub23: the Turing BinderHub
+
+**Note**: this likely needs updating, last revision was in Nov 2019.
+
+**Note**: Hub23 is not being looked after and it is not currently active.


I don't think we should publish this if there is no Hub23.

JimMadge · 2023-06-19T14:50:33Z

content/docs/technical_practices/how_to_use_hub23.md

+
+## Troubleshooting
+
+If you have any problems, check out the [mybinder documentation](https://mybinder.readthedocs.io/en/latest/), [open an issue](https://github.com/alan-turing-institute/hub23-deploy/issues/new) on the deployment repo, or ask Sarah Gibson.


Sarah hasn't worked with us for a while.

In general, I think we decided to avoid using names and instead link to the internal list of responsibilities/contacts in the REGistry.

dsj976 · 2023-06-19T16:18:38Z

Hi @JimMadge. I've just spoken to @triangle-man. Essentially, I have the task of moving all information that is public from the REG and Hut23 wikis to the Handbook. The REG wiki, which is visible to all of the Turing, should be retired, while the Hut23 wiki should only contain information that is private to REG. As I am the only person working on this at the moment, I believe I don't always have enough information to be able to make the call of whether something should be deleted or not. So I propose the following strategy:

If a page is obviously outdated and no longer applicable, I will leave that in the Wiki and label it appropriately.
For stuff that should be moved or I am not sure about, I will open a PR in the Handbook repo.
I will ask you, @triangle-man and @andrewphilipsmith for feedback and modify the PR accordingly. The PR doesn't have to be perfect - we can clean up the Handbook at the end of the process (e.g. redefine content location, delete content, etc.)
Finally, we can have a review period once I have gone through both Wikis and transferred all content, during which all of REG can have a say about the changes. This will involve cleaning up the Handbook and possibly redefining its structure.

JimMadge · 2023-06-20T10:51:40Z

I really don't think clearing out the old wikis justifies knowingly putting incorrect information into the handbook.

It also isn't necessary, there is no harm in leaving proposals in PRs and sourcing feedback there. That is the point of a PR after all. I appreciate that no one person is going to know if all information on the wikis is correct. However, that knowledge does exist across the team and we should be using GitHub mentions and requested reviewers to bring that knowledge in.

Regarding a review period after merging; we already have the problem with the wikis (and handbook) that information goes stale. I don't like the idea of kicking the can down the road and saying all of REG can fix it later. It hasn't happened before and I don't see what is different now. I'm also quite uncomfortable that this is placing an expectation that someone else should fix problems later, rather than inviting people to contribute to PRs.

@triangle-man It feels like we have a clash of priorities here, where the optimal route to deprecate the wikis is having negative impact elsewhere.

Suggested amendments to the process above,

One PR per page (roughly) – which will stop out of date pages blocking others from being merged
Invite input on PRs more broadly
Deprecate wiki pages when a PR is created
Merge when we are confident

Does that free you to draw a line under the wikis sooner?

triangle-man · 2023-06-20T11:04:52Z

Hi @JimMadge , @dsj976,

Right now we have information -- both right, wrong, and unknown -- in multiple places. I'd rather have it in fewer places.

Can you propose a way to achieve the following:

I'd like to pick a date -- say, 1 August -- when we will definitely close the current wiki.
There is no guarantee a random person will respond to a PR within that time.
If I am required, I could spare, say, 1 hour every other week to review something?
But I really would like to close the wiki by some specified date, no matter what.

That might be your proposal Jim, with the caveat that all PR's will be merged on the deadline.

Agree with you Jim that I can't see an optimum solution (because of 2), only a trade-off. If you're asking me, my trade-off is to get stuff in fewer places. However, @dsj976, @thobson88 and @andrewphilipsmith are in charge of the Documentation Service Area, so it's their call.

JimMadge · 2023-06-20T12:38:03Z

Is the hard line on PRs being merged because we want to replace each wiki page with a link to the 'new place' and we don't like linking to PRs or branches? I can see the benefit, but it feels fragile if we are expecting to delete/move things anyway.

In any case, I think the difference here is I don't see why not merging/closing PRs would prevent closing the wiki. The information isn't lost, it is in branches on the remote. It just isn't published on the site.

Or, if we could, before the deadline, organise a Dugnad style sprint to close/merge all PRs related to the wiki migration?

These things appeal to me,

If we can't get an approving review, it probably means we are not confident about the information.
We have a slightly higher threshold to publishing information as the site is public.

triangle-man · 2023-06-20T12:58:34Z

In any case, I think the difference here is I don't see why not merging/closing PRs would prevent closing the wiki. The information isn't lost, it is in branches on the remote. It just isn't published on the site.

Oh I see! Apologies, I had not understood your suggestion correctly. That makes total sense.

In which case, I've no objection to open PRs, as long as the wiki page has gone.

dsj976 · 2023-06-28T09:44:14Z

Hi @JimMadge @triangle-man,

I think what you discussed above makes a lot of sense. OK, I will follow the suggestion of "one PR per page (roughly)". For every PR I open to the Handbook (to move content into it), ~~I will open a PR with the same name to the wikis (to remove that same content from them)~~. So, for every PR that is merged into the Handbook main branch, we just need to remember to merge that same PR into the wiki's main branch.

Does that sound reasonable?

Updating the above - I just realized that while you can create local branches for a GitHub wiki, you cannot see the remote branches on GitHub or open PRs for wikis (see info here). So I will simply have to merge the branches locally and push the changes to the default branch to make them live, once the relevant PR to the Handbook has been approved.

dsj976 · 2023-06-28T10:00:03Z

If I am not sure where to put a specific page in the Handbook, I will just dump it to a "Miscellaneous" section. People can then comment on the PR to discuss the best place for it and I can update the PR accordingly

dsj976 · 2023-06-28T16:31:34Z

closing this PR because it has been broken up into smaller PRs, following conversation above.

dsj976 added 12 commits June 7, 2023 15:08

move acronyms and abbreviations from hut23 wiki to handbook

f57e525

move azure make vm with cli from hut23 wiki to handbook

677fc39

move azure from REG wiki to handbook

c576418

fixing broken links in azure section

61a9992

run pre-commit on all files

f93eaca

move books and journal access from hut23 wiki to handbook

50beac3

change weight of books and journal access

fd422ee

add note "review required"

ad9529c

fix markdownlint errors

d008120

move how_to_use_hub23 from hut23 wiki to handbook

69a5390

fix CI errors

4d38e7f

add note saying Hub23 is not active

768fa21

dsj976 requested review from triangle-man, JimMadge and andrewphilipsmith June 19, 2023 13:55

JimMadge requested changes Jun 19, 2023

View reviewed changes

dsj976 mentioned this pull request Jun 28, 2023

Move sections on Azure from Hut23 and REG wikis to the Handbook #110

Open

dsj976 closed this Jun 28, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reorganise documentation - Round 1 #107

Reorganise documentation - Round 1 #107

dsj976 commented Jun 19, 2023

JimMadge left a comment

JimMadge Jun 19, 2023

dsj976 Jun 28, 2023

JimMadge Jun 19, 2023

dsj976 Jun 28, 2023

JimMadge Jun 19, 2023

dsj976 Jun 28, 2023

JimMadge Jun 19, 2023

dsj976 Jun 28, 2023

JimMadge Jun 19, 2023

JimMadge Jun 19, 2023

JimMadge Jun 19, 2023

JimMadge Jun 19, 2023

JimMadge Jun 19, 2023

JimMadge Jun 19, 2023

dsj976 commented Jun 19, 2023

JimMadge commented Jun 20, 2023

triangle-man commented Jun 20, 2023

JimMadge commented Jun 20, 2023

triangle-man commented Jun 20, 2023

dsj976 commented Jun 28, 2023 •

edited

Loading

dsj976 commented Jun 28, 2023

dsj976 commented Jun 28, 2023


		## How to be added onto the BL journal access

		Note: this section needs reviewing, might be outdated.


		# Azure

		Azure is Microsoft's cloud service. The Turing has a grant from Microsoft to use this.


		## Troubleshooting

		If you have any problems, check out the [mybinder documentation](https://mybinder.readthedocs.io/en/latest/), [open an issue](https://github.com/alan-turing-institute/hub23-deploy/issues/new) on the deployment repo, or ask Sarah Gibson.

Reorganise documentation - Round 1 #107

Reorganise documentation - Round 1 #107

Conversation

dsj976 commented Jun 19, 2023

Summary

Related issues and PRs

Updates

JimMadge left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dsj976 commented Jun 19, 2023

JimMadge commented Jun 20, 2023

triangle-man commented Jun 20, 2023

JimMadge commented Jun 20, 2023

triangle-man commented Jun 20, 2023

dsj976 commented Jun 28, 2023 • edited Loading

dsj976 commented Jun 28, 2023

dsj976 commented Jun 28, 2023

dsj976 commented Jun 28, 2023 •

edited

Loading