Add a guide for managing shows

[sharifsalah]

Add a how-to guide to introduce creating and managing shows from the cueadmin command.

The how-to guide would probably cover the following options to introduce the cueadmin command and the various requirements to get started with submitting jobs:

-create-show 
-delete-show 
-disable-show
-enable-show 
-dispatching 
-booking 
-default-min-cores
-default-max-cores

[bcipriano]

Great idea.

Side note, is it worth it to add a "documentation" label for issues like this one?

[sharifsalah]

Thanks, a docs label would be very useful for both this repo and opencue.io.

So thinking about this a bit more, I'm wondering if it might be good to separate out docs issues for both projects along the following lines:

• Issues related to docs generated from the OpenCue code base, such as API reference docs, command help pages, and README files would live under the OpenCue repo.
• Issues related to managing opencue.io, as well as issues related to the blog, release notes, user guides and other user feedback about the docs would live under the opencue.io repo.

There's a couple of reasons behind my thinking:

• It aligns with other OOS projects using a similar docs stack to OpenCue, such as kubernetes.io (which for the benefit of anyone else reading, is owned by the Linux Foundation).
• opencue.io includes a Create issue button on every docs page (See this page for an example). When a user clicks this button, they can create an issue which is logged against the opencue.io repo. So this would reduce confusion by consistently logging user-facing issues in the docs repo.

What do you think?

[bcipriano]

I'm torn on this one. I understand your reasoning and your idea for how to divide issues between repos makes sense. On the other hand I see it getting very confusing having two separate issues lists. The added burden to triage/assign issues in a second repo might mean that some issues (opencue.io ones, specifically) get missed.

Apparently there is no OR search operator in Github (https://stackoverflow.com/questions/29136057/can-i-search-github-labels-with-logical-operator-or) which seems like it would make it difficult to see a list of issues across both repos. Unless we use some third-party or custom tooling to do this.

To help decide what our options are: is there a way to configure a custom repo for the "Create issue" button, in order to for example redirect all new issues to the main OpenCue repo?

[sharifsalah]

That's interesting and a shame that we can't use OR search operators.

I tested the way Docsy works and while we can configure the destination repo for the Create issue button, this would also override the behavior of the Edit this page button, as that also relies on the value of the repo to direct the contributing user to the relevant underlying Markdown file they need to edit to update a page.

Are you thinking that contributors are going to click Create issue and add non-docs issues to the opencue.io repo? (Which seems quite possible)

There are several ways I think we could mitigate against this:

1. Update our installation of Docsy to add a second button for creating issues. I'm not sure what the exact UX would feel like just yet, but I'm thinking something like two buttons: (I suspect this might be useful for other Docsy users as well, so I could always propose the change to that project)
   1. Create OpenCue issue
   2. Create docs issue (this is actually what I think the current button is implying, but I can also appreciate how it might not be clear to all users)
2. Implement issue templates for opencue.io to remind to contributors that they should open issues for OpenCue in it's repo. For an example of how Knative does this, see their docs issue template.
3. As a final resort, GitHub offers a feature to transfer issues between repositories. I found out about this from colleagues (**) managing open source docs for other projects who use this GitHub feature as part of their triaging process.

(**) For more examples of docs issue lists, see Knative docs, istio.io, kubeflow.org, and kubernetes.io issues.

If all or some of the above mitigation steps sound reasonable, we could run a trial to manage docs issues in opencue.io and see how it goes?

[bcipriano]

Are you thinking that contributors are going to click Create issue and add non-docs issues to the opencue.io repo? (Which seems quite possible)

Yes, seems very likely that users will do this.

There are several ways I think we could mitigate against this:

Of these, (1) feels most helpful.

(2) feels like it will be either ignored or scare some folks away. Filing bugs is already unfamiliar territory for non-technical folks and adding a decision point here feels like it raises the barrier to entry perhaps too much. (As opposed to (1), which still adds a decision but it's graphical -- easier to convey our point using icons instead of text.)

(3) is good to know about, but I wouldn't want to rely on a manual process, as those sorts of things tend to slip and eventually be forgotten IME.

I like the idea of doing (1) and later trying to contribute it to Docsy. Sorry to ask you to do more work but if there's some way I can help let me know.

[sharifsalah]

Great, thanks for the feedback. Agreed that (1) is likely to be helpful and worth trying. I don't think we have enough data either way to determine the impact of (2) but no urgent need to experiment for now. Also agreed that (3) could be unreliable in the long term.

I've staged a preview of what (1) could look like at: (the right-hand page links, above the table of contents)

https://5cfe8ee8834e4700072e8dc2--elated-haibt-1b47ff.netlify.com/docs/user-guides/submitting-jobs/

This is not perfect for a couple of reasons:

• The links appear on all site pages (except the home page), even those where they might not be overly relevant, such as landing pages.
• The UI string Create documentation issue is quite long, but I'm reluctant to switch to the shorter docs as we consistently refer to it as documentation. The string will wrap on smaller laptop screens. The right column is never visible on mobile.

However, I think it's an improvement over the current system.

PTAL and let me know what you think.

[bcipriano]

LGTM! The points you mentioned don't bother me much.

[sharifsalah]

Great thanks. After I heard back from you, I reached out to the Docsy team and they would very much like me to contribute the change to that project so that the wider community can benefit (everyone seems to agree the current UX is confusing).

Rather than apply it to opencue.io and then Docsy and then remove it from opencue.io (to replace it with the Docsy version), if it's OK with you, I'm just going to go ahead and contribute a PR to Docsy.

I'll add an issue to opencue.io so that we don't lose track of this and I'll share the PR with you (in our issue) so that you know what changed in Docsy for future reference if we need to revisit.

[bcipriano]

Sounds great! Love to see us contributing back to other projects already.