Previews for OnDemand and RStudio pages are up

[hgputnam]

RStudio https://www.c4.ucsf.edu/howto/rstudio-server-2.html OnDemand: https://www.c4.ucsf.edu/howto/openondemand.html

[hgputnam]

I still need to do one for Jupyter. I suspect that one will change a lot as I get feedback from beta testers. I am not really capable of testing that right now (not a python expert)...

[HenrikBengtsson]

Let's start with copy-editing:

• [x] Capitalization (cough cough), e.g. Rstudio, r, rstudio server, ...
• [x] Lack of inline code Markdown markup, e.g. 'Equivalent to –ntasks in sbatch.' -> Equivalent to –ntasks for sbatch.
• [x] Step2 -> Step 2, etc.
• [x] GB -> GiB
• [x] --mem 16g, ..., --mem 32g -> --mem 32G
• [x] Spelling, cf. https://github.com/UCSF-CBI/c4/actions
• [x] Ctrl-C -> <kbd>Ctrl-C</kbd> to get Ctrl-C

Do we really need all those screenshots? Can't we explain most of those steps in text, and then use images only for what otherwise might be confusing? The more screenshots we have, the more time we need to spend to regenerate them whenever the software (here OnDemand) is updated. Screenshots tend to become outdated quickly in general.

Also, they consume lots of real estate, e.g. on my laptop I cannot even fit an image in one screen. I need to scroll to see it:

I propose to regenerate the once to keep using a much smaller browser window with bigger text.

[hgputnam]

It was a pretty huge pain in the neck to put those images in. I am not in love with them in any way. I thought that was what we needed for a GUI product. Example of regeneration problem you mention - I already fixed a bunch of the Capitalization, GB, on the real froms but of course never updated the images.

If you are cool with no images I will take them all out.

[hgputnam]

Also, it is RStudio right?

[hgputnam]

And, to be fair, I did ask #62

[HenrikBengtsson]

Yes, I saw. I just haven't had the time.

What I think we could benefit from is to have a C4 blog where one can write up longer walk-throughs. The advantage with that is that they are dated and are allowed to become old and obsolete over time. In contrast, the website is the documentation, so it has to be up-to-date and any discrepancies and errors have to be fixed asap, otherwise the user cannot trust the info. Also, with a blog, we can invite guest writers to write about their tips and tricks. Then one can reference the different C4 blog posts from the C4 website. Oh well, it's on my todo to look into that.

[HenrikBengtsson]

Regarding going live, I think we shouldn't rush it. Let's have a few advanced users use it first to sort out the wrinkles. I'm sure there are plenty and as we learned these last two weeks there are still to be improved. I would also suggest to hold back on Jupyter, and just go live with the RStudio Server. From that, we'll learn more things that we can apply to Jupyter, which I also have not had a single look at yet. Who knows, now when rsc is in a pretty good shape, maybe we can put together a Jupyter Notebook Controller tool.

[hgputnam]

Yeah, I totally get your point about the docs and the images getting stale (which they already are). We just have to fact the fact that I am an awful technical writer. I do not enjoy it one bit and yes, I do tend to rush it (just to get it over with) and I make even more mistakes than normal. I can only type like 20 word/minute...

So, I was planning to use these to hand off to the beta testers. I was going to say that the documents are being beta tested along with the software and make enhancements based on feed back. How about:

• [x] Remove all the stupid images and never speak of it again.
• [x] I pinky swear to use make check more..
• [x] Give those to the beta testers.

go from there...

[HenrikBengtsson]

Sounds like a good plan. I wouldn't call the images "stupid". The one showing the OnDemand RStudio being available, helps communicate what to expect and probably is more appealing and selling than plain text. I think you write well.

[HenrikBengtsson]

@hgputnam, since we now got beta-tester eyes on it, don't forget to fix up the remaining documentation issues: https://github.com/UCSF-CBI/c4/issues/63#issuecomment-1036765306. We want to spare them from having to re-report these issues too.

[hgputnam]

These are cleaned up to the point they get past make check. I think I have incorporated your formatting advice:

https://www.c4.ucsf.edu/howto/openondemand.html https://www.c4.ucsf.edu/howto/rstudio-server-2.html https://www.c4.ucsf.edu/howto/jupyter-notebooks.html

[HenrikBengtsson]

Nope, none of my comments (https://github.com/UCSF-CBI/c4/issues/63#issuecomment-1036765306) have been addressed. I've attached a PDF where I highlight what I'm referring to.

UCSF C4 Cluster.pdf

[hgputnam]

9 millionth attempts are up.

[HenrikBengtsson]

Thanks

[HenrikBengtsson]

I did some tidy of the RStudio Server page (https://www.c4.ucsf.edu/howto/rstudio-server-2.html).

My gut feeling is that, after you've now harmonized the OnDemand configuration, the sections for running RStudio, Jupyter, Desktop, ... via OnDemand will be very similar, i.e. there's a lot of redundant information across these pages. My suggestion would be to

• [x] Have a single OnDemand (https://www.c4.ucsf.edu/howto/openondemand.html) page that covers all tools, i.e. the generic configs and then say you can launch RStudio, Jupyter, Desktop, ... this way. This is analogue to how we have one GUI page (X11 and X2Go)*

Then,

• [x] on the "how-to" pages for the RStudio Server, Jupyter, ... focus on the solution done at the command-line over SSH. Of course, these pages should mention that these tools can be run via the C4 OnDemand and link to the OnDemand page.

This way, an "OnDemand" user don't have to worry about reading the "terminal" instructions, and vice versa. (* For the reason, I think we might want to split up the X11 and X2Go page in to two separate one). From a maintenance point of view, this will also have less redundancy, meaning fewer places to update when there's a change. Keeping the website up to date is what requires most attention and time.

What do you think?

[HenrikBengtsson]

FWIW,

• [x] I've deprecated the old 'Work with RStudio Server' page (https://www.c4.ucsf.edu/howto/rstudio-server.html) that uses Singularity, and replaced it with a new 'Work with RStudio' (https://www.c4.ucsf.edu/howto/rstudio.html) that shows how to run the RStudio Desktop (X11) and RStudio Server (rsc) on a dev node.

This new page does not mention the third OnDemand alternative. I still think OnDemand should have its own, separate page, especially since the instructions can be quite simple.

[HenrikBengtsson]

I've now removed the old, redundant, never published https://www.c4.ucsf.edu/howto/rstudio-server-2.html.

Closing ...