Arvados

Currently we have screenshots with developers' usernames and email addresses, and the reader is left to wonder whether the choice of "asmith" in one screenshot and "bjones" in another is meaningful or just sloppy.

• Choose one demo site, e.g., cloud.curoverse.com. When making a screenshot, you have two choices:
  • Use the one real demo site. (This works when the relevant feature has already been deployed and is appropriate to experiment with there.)
  • Use a dev or staging instance, but take the time to make it look exactly like it would on the real demo site. For example, the top nav should have the same brand/title, the same set of features should be configured/enabled if that affects the display, etc.
• Create one regular (non-admin) user at the demo site, belonging to a fictional character. Not Dax, because Dax is already a character inside Arvados -- maybe Danet Daxon?
  • Screenshots of a non-admin feature should be made while logged in as Danet.
• Create one admin user at the demo site -- Lumberg? Mr. Burns? -- and use it for screenshots/examples for admin features.

Additionally we have some "uuid_prefix.your.domain", some "uuid_prefix.example.com", some "qr1hi.arvadosapi.com", and perhaps some others.

• Use "uuid_prefix.yourdomain.example" instead of *.your.domain and *.example.com. Rationale: *.domain is not a reserved TLD, but *.example is. *.example.com is awkward when discussing multiple domains: "yoursite.example.com" and "theirsite.example.net" is necessary to make it clear they don't belong to the same company; compare "yoursite.example" and "theirsite.example".
• We made the qr1hi part customizable at doc-build-time, but we don't yet include "install your own customized docs" to the install process, so users at foobar.example are still reading docs that say qr1hi.arvadosapi.com.
  • We could add "install your own docs" to the install process.
  • We could add javascript code to the docs so you can type your own "uuid_prefix.yourdomain.example" into a text box at the top, and the whole doc site would start using that in the appropriate places.