Arvados

Our documentation is under doc and written using both Textile and Liquid.

Liquid is the templating language, like Jinja. It fills in variables and dynamic includes into the text. When you see {{ variable }}, {% code %}, or {# comment #}, that's Liquid.

Textile is the markup language, like Markdown. It's the same syntax that Redmine uses in our tickets. This covers all the stuff HTML does like headers, links, tables, lists, etc.

For this ticket you can probably find what you need from context, but if you end up with questions, there are the references and the explanation for what is what.

Feel free to think out loud on this ticket. None of this is required but good steps would be:

• simply identifying all the pages and screenshots that need to be updated
• and then maybe categorizing them by how much update they need. Just a screenshot swap? Minor text change? Major text rewrite (e.g., totally different flow)?
• and then start tackling those progressively. e.g., if you want to get your feet wet with a branch that just changes the easy screenshot swaps, that sounds cool to me.

Like I said, this specific process isn't required. My main point is really, I don't expect this ticket to be done in a single, fully-formed branch. It can be iterated on.

22464-update-screenshots @ 55ecf415e2b11108637b93709386bea5607a20ba

• ✅ All agreed upon points are implemented / addressed.
  • The UI changes that prompted the need for screenshot updates are currently only on tordo, and some of the screenshots refer to the WGS tutorial that uses a workflow registered only on pirca. Either the tutorial workflow needs to be registered on tordo or we need to wait until the changes on tordo are pushed to pirca.
  • Skipped screenshots in:
    • tutorials/wgs-tutorial.html sections 3b and 4a
    • all sections of tutorial-keep.html
• ✅ Anything not implemented (discovered or discussed during work) has a follow-up story.
• n/a Code is tested and passing, both automated and manual, what manual testing was done is described
• n/a New or changed UX/UX and has gotten feedback from stakeholders.
• ✅ Documentation has been updated.
• n/a Behaves appropriately at the intended scale (describe intended scale).
• n/a Considered backwards and forwards compatibility issues between client and server.
• n/a Follows our coding standards and GUI style guidelines.

Lisa Knox wrote in #note-8:

The UI changes that prompted the need for screenshot updates are currently only on tordo, and some of the screenshots refer to the WGS tutorial that uses a workflow registered only on pirca. Either the tutorial workflow needs to be registered on tordo or we need to wait until the changes on tordo are pushed to pirca.

I think the best process we have available to us is: the person making new screenshots runs a development Workbench out of the Arvados main branch which is configured to talk to pirca as its API server. Ideally, it would report its version as 3.2.0 (or in the future, whatever version we expect to release next). I believe this would let you access everything on pirca, and have it looking as close as possible to pirca (including little details like UUID prefixes), while letting you use the latest Workbench features.

There are some specific cases where this wouldn't work, like when Workbench relies on new API features. But for stuff that's already documented, I think this would work for updating screenshots. Our login cluster is configured to let you do this for a Workbench running on localhost:3000. Is there any obstacle I'm missing that makes it difficult?

For what's here so far:

• In general, I don't know if I have a strong opinion about how we draw attention to specific parts of screenshots, but I think we need to stay consistent. I think the bulk of our current screenshots highlight the background in yellow. You're using red outlines and arrows. I think I'm leaning towards keeping the yellow background just because I think it's easier for us to document a process to do that consistently. With red markup where there are more variables you have to get right (shape, length, brush size). Do you feel strongly about red markup? If not, I can take on the work of documenting that process for how to highlight screenshots.
• On doc/user/tutorials/wgs-tutorial.html.textile.liquid, "You can also download a file to your local machine by right-clicking a file and selecting "Download" from the context menu, or from the context menu available by right-clicking on the listing." - I don't understand the difference between these options. Personally I think it would be fine to just delete one. I do not think we need to document every way to do every thing, especially not in the tutorial. But I'm also open to just clarifying the difference.
• On doc/user/getting_started/vm-login-with-webshell.html, the screenshot still seems okay but the text describes accessing "Virtual Machines" in the user menu, not "Shell Access" in navigation as today.

Here are some notes about pages you skipped, if we punt this to a future ticket that's okay, just want to record it while I'm looking:

• On doc/user/tutorials/tutorial-keep.html, the screenshots need updating.
• On doc/user/tutorials/tutorial-keep-get.html, the sharing dialog and text with it both need updating. The text says "locate the collection and then go to the Sharing settings dialog box as described above" - but there is no such description above.

Thanks.

22464-screenshots @ bcda07829b18cbd1de45773d143cffc4ce50a79a

I started over, going through and replacing all screenshots in doc/user, using yellow highlighting to indicate elements as suggested. There was no real driver to use arrows instead of highlighting other than the general accessibility principle that one should avoid using only color to indicate something, but it's a very minor concern in the tutorial, probably not an issue in practice. I also went through and updated wording where appropriate. I did not re-run the test suite as documentation is the only change.

In the future, it may be wise to institute a yearly review of all of our documentation to catch any issues like this proactively, perhaps an end-of-year task.

We do actually have documentation tests. Mainly, they check that all links work. This can be helpful to make sure you didn't accidentally typo a link. A version for just the hand-written documentation runs as part of developer-run-tests, and then this tests that along with all SDK documentation: developer-run-tests-doc-sdk-java-R: #2249

I noticed little punctuation and spelling issues along the way. Because describing changes to prose takes way longer than just making the edits, I just pushed my changes to the branch in 5c6c6ab0f7dbf43222b40bc4bdb1ac5bee80d40d. Please take a look, and if there's anything you think is an issue, please let me know.

All the new screenshots highlight the right things and the updated text is good, thank you. My only real issue from here is the way the highlight was done. It looks like you selected an area around the thing of interest and then applied highlight with the fill tool. This works fine for buttons and icons, but when there's just plain text against plain background like menu items, it means loops in letters like d, p, and o stay white. IMO it looks really ragged to the point of being distracting. I would like this to be cleaned up. At this point, as silly as it is, it probably is simplest and fastest to just go through each screenshot and fill the loops by hand. But I'm not particular about how it gets done, just the end result.

I would also like this to be brought up-to-date with recent main. The fact that review took a week is not on you at all, and if that was the only gap I could live with it, but it seems like the branch broke off three weeks ago and that could be tightened up.

What would be ideal is we cleaned up screenshots, and then rebased on current main, such that the new set of screenshots were the only ones committed to the rebased branch, and the current set of screenshots (the ones I'm reviewing) never hit main history. Since binary files in Git are relatively expensive, it's nice if we can avoid keeping more than we need to.

Happy to talk about how we should go about that process-wise. Thanks.

22464-screenshots-rb @ 010197cbb505246d32b01fab8710e26ce6dfe1de

Screenshots updated to fill in the white holes and changes rebased on top of main.

Lisa Knox wrote in #note-14:

22464-screenshots-rb @ 010197cbb505246d32b01fab8710e26ce6dfe1de

developer-run-tests-doc-sdk-java-R: #2250

The changes LGTM, thanks. I would like the commits that change the screenshots to be squashed together so that when the branch gets merged to main, there's only one commit that updates all the big binary screenshots, not a series of them. If you're not sure how to do this, let me know and I can either walk you through it, or I could do the merge myself if you prefer, it's a quick operation. Thanks.

22464-screenshots-rb3 @ 4df6cf6ca6377571c09ad6e658412b45bc9ae1d9

Squashed and rebased as suggested

Lisa Knox wrote in #note-16:

22464-screenshots-rb3 @ 4df6cf6ca6377571c09ad6e658412b45bc9ae1d9

Squashed and rebased as suggested

Perfect, LGTM, thank you.