Documentation improvement

UCL-RITS / mkdocs-rc-docs

Experimental Research Computing documentation generation using mkdocs

http://rits.github-pages.ucl.ac.uk/mkdocs-rc-docs/

29 stars 19 forks source link

Documentation improvement #59

Open heatherkellyucl opened 1 year ago

heatherkellyucl commented 1 year ago

To do:

[x] Link to our two Moodle courses on our front page
[ ] Link to relevant video sections from the Intro to HPC course using the MediaCentral links in suitable places throughout our docs
Identify gaps in documentation and add these as GitHub issues in that repository.
- eg the walkthroughs section is fairly empty
Identify whether there are changes to the organisation of our docs that would be helpful and add these suggestions as one or more GitHub issues in that repository.
- eg are there places you would expect certain information to be and it isn't
- are you looking for info and can't work out where it should be found
After the first pass through and suggestions, see if Camilla, Fatima and Brian have any additional thoughts or feedback.

heatherkellyucl commented 1 year ago

We discussed in our meeting about making sure it was clear what should and should not be run on the login nodes.

From @cdkharris :

We brought up abuse of the login nodes during our meeting this morning. The first place i found mention of it in the user-facing documentation is in the terms and conditions. In the mean time, before we can automatically enforce this, it would be good to add a bulletin/reminder to the top of the R Software Guide, and the page for new users, and maybe the login banner for myriad. the reminder should say something like "Do not run memory-intensive tasks on the login nodes. Your program may be killed without warning at any time. To run a production-scale program interactively, please request an interactive job (https://www.rc.ucl.ac.uk/docs/Interactive_Jobs/)."

heatherkellyucl commented 1 year ago

https://www.markdownguide.org/cheat-sheet/

heatherkellyucl commented 1 year ago

All our HPC course videos are globally viewable at https://mediacentral.ucl.ac.uk/ if you search for HPC, so you can get links from there if you can't from Moodle.

heatherkellyucl commented 1 year ago

If you complete all the above, have a look in https://ucl.lightning.force.com/ at RemedyForce Console > ARC.Research Computing Support at our tickets and see if there are any that seem to benefit from better documentation, make note of the topic (and possibly ticket number) in here.

ikirker commented 11 months ago

and maybe the login banner for myriad.

The motd is already pushing it for length. If even more stuff is being added, it would probably be worth either removing some of it, or moving some of the legal stuff (that should change relatively infrequently) into the actual banner (the one that gets shown before authentication).

cdkharris commented 10 months ago

Many tickets come down to confusion about which clusters support MPI. It would be good if the example job scripts indicated whether they were appropriate to run on Myriad.

For example, the RMPI and Snow script could have a comment or a note in the description that it will not work on Myriad but is suitable for Kathleen, especially since the opposite is true of the previous scripts on the page.

heatherkellyucl commented 10 months ago

It will still work on Myriad though - but within a node. The sizes of jobs that clusters will run are listed on the cluster-specific pages. We have quite a large number of people running within-node mpi jobs.