guide: add beginnings of a user guide

[oliver-sanders]

No description provided.

[codecov-io]

Codecov Report

Merging #215 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##           master   #215   +/-   ##
=====================================
  Coverage       0%     0%           
=====================================
  Files          16     16           
  Lines         226    226           
=====================================
  Misses        226    226

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 019cda2...0aa1ca8. Read the comment docs.

[wxtim]

I notice that the "special task states" doesn't scale to full width on smallish screens. On very old phones it might look even worse:

[wxtim]

Nothing other than the comment about the styling. I think it would probably be better sorted out now rather than later, but is low priority.

[sadielbartholomew]

#155 is the Issue I mentioned in the offline discussions on this just now. In short, ideally we can incorporate user guidance into the UI via means of e.g. a tour or (carefully designed & placed) tooltips or similar, rather than have it as a separate tab or page, where it essentially becomes documentation in my eyes. And I don't think any good UI should need documentation!

[hjoliver]

@sadielbartholomew -

And I don't think any good UI should need documentation!

Maybe you're right in principle, but I tend to think we should have a documentation page as well in case we fail to quite live up to that lofty goal, and besides I think at least some users might prefer a minimal documentation page with all the necessary information in one place - e.g. task state meanings, what the various views are good for, etc. Plus some of this information isn't strictly "UI" - it's about the meaning of the data that the UI displays (maybe we could replace that with tool-tips or similar ... but that might be annoying; or an optional UI "tour" ... but that would likely need to be a future enhancement?).

So I'd suggest merge this (when it passes review), and add to it as we go, and consider removing it in the future if our UI turns out to be so staggeringly intuitive that the documentation isn't needed! Is that OK with you?

[hjoliver]

LGTM, apart from the problem mentioned by @wxtim. Which seems to be caused by this CSS (the values should be 100%; not sure how to fix though as it's not part of this branch):

[hjoliver]

Also: need a link from the dashboard page?

[hjoliver]

(Having made two suggestions for changes, I suppose I should revoke my initial approval!)

[kinow]

Will leave merging up to @oliver-sanders. We can merge as-is and open other PR's to link to the page from the dashboard (I think that's where the link will come from?), and address my comments. Or make further changes here, either way is fine for me as this is new code, doesn't break anything so can be merged with no issues 👍

And really liked being able to see the job and task states side by side. As well as having a place for the special states 🎉

[kinow]

Maybe we can use Vuetify typography and flex grid (will change a bit when we have vuetify 2)?

Removing the styles from here, and using the code from this PR oliver-sanders#1

• Before & after diff desktop:

• Before & after diff mobile:

Might still need some adjustments, but that would be easier to be adjusted to Vuetify 2 too (WIP #11).

(Also added some review comments showing what I did basically)

[oliver-sanders]

Maybe we can use Vuetify typography and flex grid (will change a bit when we have vuetify 2)?

Any reason to change from using a table? Happy to use Vuetify components if they are higher quality, but in this case I don't think they are.

[kinow]

No special reason. I only used these Vuetify components because they translate to flex, flex-wrap, nowrap, and flex columns with %s, etc, and I was using them in the Tree view recently. I can try to achieve the same with a table 👍

[kinow]

@hjoliver sorry, started reviewing in the morning and didn't see your review until I submitted mine.

Also: need a link from the dashboard page?

There's a TODO for it somewhere I think. But if that's a new link in the dashboard, that will balance the links, and we will have 3 links on each side 😬

[hjoliver]

No need for sorry - you did a proper review! 👍

[oliver-sanders]

I don't think any good UI should need documentation!

I know what you mean, a good UI should just be obvious, but the Cylc UI definitely needs explaining. At present most users are unaware of many of the useful features of the current Cylc GUI so there is definitely a documentation gap we need to cross.

There are good UIs which have documentation e.g. GitHub.

I don't think we should write a user manual for the GUI, perhaps "guide" is the wrong word but there are things like task-job separation which definitely need explaining.

The modern approach to GUI docs seems to be little bitesize chunks of easily digestible information which get slowly dribbled through to the user (very agile). As we add features I think we should write little "cards" to go along with the changes (like the ones in this PR) telling users about the new feature and how it works.

The "guide" page is just the place where these "cards" live. Users don't necessarily browse to this page for help, we could link to a "card" from within the GUI.

To re-use GitHub as an example they have a chengelog with "cards" containing information about new features, users get linked through to the changelog from the UI (they also have a blog for longer reads). The "Guide" page is a more "browsable" version of this changelog providing everything in one place for those motivated souls who want to find out more.

[sadielbartholomew]

So I'd suggest merge this (when it passes review), and add to it as we go, and consider removing it in the future if our UI turns out to be so staggeringly intuitive that the documentation isn't needed! Is that OK with you?

Yes, that's okay by me. Oliver clarified some of the points of the offline discussion we had in his comment above.

I don't think we should write a user manual for the GUI, perhaps "guide" is the wrong word but there are things like task-job separation which definitely need explaining.

I agree that most of the aspects that will need explaining for certain relate to new facets such as task & job separation. And whilst these are represented by state icons etc., ultimately they are not pure UI aspects but Cylc logic ones.

I think at least some users might prefer a minimal documentation page with all the necessary information in one place - e.g. task state meanings, what the various views are good for, etc.

Fair enough, & probably true, but in that case I would wonder why it should go in a tab of the UI & not in the documentation proper. In fact, I think as a UI tab we might risk wasting a significant amount of UI server resource, as users might open a dedicated tab just for reading the guide (or even multiple ones 😟) & flick to-&-from it for advice? If necessary could we mitigate the server load for the guide endpoint in some way, maybe?

I'm not going to push for a different approach, but I'm raising some conerns 😁! Certainly for now this is good enough way to incorporate the guidance content (which looks great so far, BTW).