Tips for effective colab authorship

[dmarx]

🎈 Feeling Inflated

• scrollytelling 'wizard' (a la "installation wizard")
  • segment options into sets of decisions presented sequentially to the user
  • DAG flow through options
• notebook tells a story, follows a clear path through
  • if it's not important to the story, the user doesn't need to see it.
  • don't make user run cells that don't have decisions (i.e. forms) attached to them.
• abstract away as much as possible into a backend library
  • this is one of my more contentious opinions
    • this approach prioritizes user experience over hackability
    • Katherine Crowson is the queen of hackable colabs. the main recipe there is functional programming + fully-self contained notebooks (i.e. offloading basically nothing into a backend library so it's directly exposed in the notebook for hacking)
  • reusable parts
  • application code isolated from view
  • notebook layout easier to modify
  • less vulnerable to regressions
• limit how much the user needs to think about at a time.
  • people are easily overwhelmed
  • group parameters together visibly.
  • use documentation to create visual distance between groups if necessary
  • advanced options collapsed by default
  • alternatively, 'easter egg' options (no forms)
• XDG_CACHE_HOME
• pathlib.Path all the things
  • Path(...).exists()
  • Path('~/.cache').expanduser()
  • Path(...) / 'subfolder'
  • Path(...).mkdir(parents=True, exist_ok=True)
• limit colab-specific tooling and logic
  • panel/streamlit/gradio instead of colab forms -> local GUI
• separate project state from workspace and IDE state
• separate config groups into separate files
  • analogous to scrollytelling-wizard's decision grouping
  • easier to make isolated changes
• keep inputs (i.e. settings) and outputs separate
• default to a unique filename for all outputs
  • too much (intermediate) state serialized is usually better than too little
• changelog in the notebook helps bring visibility to new features
• adding a version number in the notebook and/or title helps users identify how behind forks might be

[dmarx]

abstract away as much as possible into a backend library

I think I've officially changed my mind on this one.