Quickstart

[dberenbaum]

Report

Our current "Get Started" pages are multiple pages, going through a full project. They are useful for someone who wants to set aside time to learn dvc, but maybe not so much for people who simply want to start using a particular feature of dvc as quickly as possible in their own code. There is some discussion about this in https://github.com/iterative/dvc.org/pull/4883#issuecomment-1753663079 and it has been discussed before, but maybe we need more of a "quickstart" guide that gets people up to speed as quickly and directly as possible.

[SoyGema]

Hey @dberenbaum ! Thanks for opening the discussion about this I indeed that the docs are a great learning tool but it somehow slows things down when users might want to get things working fast. Found that somehow docs from other experimentation platforms are more user-oriented and speed things up WRT timings, naming, and content. Drafted to the discussion axis that I´m seeing here, feel free to reach out with whatever you might need on my side!

𝙸𝚖𝚙𝚘𝚛𝚝𝚊𝚗𝚝 𝙽𝙾𝚃𝙴: 𝚃𝚑𝚒𝚜 𝚒𝚗𝚌𝚕𝚞𝚍𝚎𝚜 𝚜𝚘𝚖𝚎 𝚗𝚘𝚝𝚎𝚜 𝚊𝚗𝚍 𝚛𝚎𝚌𝚘𝚖𝚖𝚎𝚗𝚍𝚊𝚝𝚒𝚘𝚗𝚜 𝚏𝚘𝚛 𝚀𝚞𝚒𝚌𝚔𝚂𝚝𝚊𝚛𝚝 𝚠𝚛𝚝 𝙱. 𝚃𝚑𝚎 𝚛𝚎𝚌𝚘𝚖𝚖𝚎𝚗𝚍𝚊𝚝𝚒𝚘𝚗𝚜 𝚊𝚛𝚎 𝚖𝚘𝚛𝚎 𝚖𝚎𝚗𝚝𝚊𝚕 𝚖𝚘𝚍𝚎𝚕𝚜 𝚝𝚑𝚊𝚝 𝙸 𝚜𝚑𝚘𝚞𝚕𝚍 𝚏𝚘𝚕𝚕𝚘𝚠, 𝚋𝚞𝚝 𝚌𝚘𝚖𝚎 𝚠𝚒𝚝𝚑𝚘𝚞𝚝 𝚊𝚗𝚢 𝚏𝚘𝚛𝚌𝚒𝚗𝚐 𝚒𝚗𝚝𝚎𝚗𝚝𝚒𝚘𝚗 𝚏𝚘𝚛 𝚝𝚑𝚎 𝚖𝚊𝚒𝚗𝚝𝚊𝚒𝚗𝚎𝚛 𝚝𝚘 𝚒𝚖𝚙𝚕𝚎𝚖𝚎𝚗𝚝 𝚝𝚑𝚎𝚖.

Docs pages

From the DOCs analysis page, I´m finding that B presents a cleaner view and 2 prioritized calls to action for a time speedup : a search bar and a Quickstart button. As per DVC , can see the search bar up , the edit on github , the get started button ... many calls to action with the same size (getting started is somehow prioritized by color and position) without specifically knowing which is the faster track.

𝙲𝙾𝙽𝙲𝙻𝚄𝚂𝙸𝙾𝙽: 𝚝𝚑𝚎 𝚌𝚘𝚗𝚝𝚛𝚒𝚋𝚞𝚝𝚘𝚛 𝚛𝚎𝚌𝚘𝚖𝚖𝚎𝚗𝚍𝚜 𝚝𝚘 𝚝𝚑𝚎 𝚖𝚊𝚒𝚗𝚝𝚊𝚒𝚗𝚎𝚛 𝚝𝚘 𝚙𝚛𝚒𝚘𝚛𝚒𝚝𝚒𝚣𝚎 𝚌𝚊𝚕𝚕 𝚝𝚘 𝚊𝚌𝚝𝚒𝚘𝚗𝚜 𝚆𝚁𝚃 𝚊 𝚏𝚊𝚜𝚝-𝚝𝚛𝚊𝚌𝚔 𝚜𝚌𝚎𝚗𝚊𝚛𝚒𝚘

QuickStart in B

If I go to Quickstart in B:

• I can select CLI or Notebook. In DVC only see CLI in Getting Started. There is this logical/rational belief that might make sense that you are not prioritizing Quickstart with DVCLive. DVCLive main page is somehow better on this and I understand it is a quickstart for experiment tracking because I know the tool - not because it is prioritized at the beginning - , and have some common structure with respect to B [1] [2]
• The structure and guidance from B in the start states to solve 3 main points and goes to Ws Common questions, Including a What´s next ? DVC literally recommends you to follow your own adventure somehow, which clearly invites you to an open-ended scenario.

𝙲𝙾𝙽𝙲𝙻𝚄𝚂𝙸𝙾𝙽: 𝚝𝚑𝚎 𝚌𝚘𝚗𝚝𝚛𝚒𝚋𝚞𝚝𝚘𝚛 𝚛𝚎𝚌𝚘𝚖𝚖𝚎𝚗𝚍𝚜 𝚝𝚘 𝚝𝚑𝚎 𝚖𝚊𝚒𝚗𝚝𝚊𝚒𝚗𝚎𝚛 𝚝𝚘 𝚊𝚍𝚍 𝚊 𝚀𝚞𝚒𝚌𝚔𝚜𝚝𝚊𝚛𝚝 𝚘𝚛 𝚌𝚑𝚊𝚗𝚐𝚎 𝚝𝚑𝚎 𝚞𝚗𝚍𝚎𝚛𝚕𝚢𝚒𝚗𝚐 𝚍𝚢𝚗𝚊𝚖𝚒𝚌𝚜 𝚘𝚏 𝚝𝚑𝚎 𝙶𝚎𝚝 𝚂𝚝𝚊𝚛𝚝𝚎𝚍 𝚜𝚎𝚌𝚝𝚒𝚘𝚗. 𝙸𝚏 𝚊 𝚀𝚞𝚒𝚌𝚔𝚜𝚝𝚊𝚛𝚝 𝚜𝚎𝚌𝚝𝚒𝚘𝚗 𝚒𝚜 𝚊𝚍𝚍𝚎𝚍, 𝚝𝚑𝚎 𝚌𝚘𝚗𝚝𝚛𝚒𝚋𝚞𝚝𝚘𝚛 𝚛𝚎𝚌𝚘𝚖𝚖𝚎𝚗𝚍𝚜 𝚝𝚘 𝚊𝚟𝚘𝚒𝚍 𝚘𝚙𝚎𝚗-𝚎𝚗𝚍𝚎𝚍 𝚜𝚌𝚎𝚗𝚊𝚛𝚒𝚘𝚜.

"Quickstart" with DVC

Non existing page is named as such. Glimpsing that DVCLive is playing an important role here, but I only discover it when I go to the Studio page, to experiments and model registry. Also known that there is a fast track for using the extension, but not presented from the start.

𝙲𝙾𝙽𝙲𝙻𝚄𝚂𝙸𝙾𝙽: 𝚝𝚑𝚎 𝚌𝚘𝚗𝚝𝚛𝚒𝚋𝚞𝚝𝚘𝚛 𝚛𝚎𝚌𝚘𝚖𝚖𝚎𝚗𝚍𝚜 𝚝𝚘 𝚝𝚑𝚎 𝚖𝚊𝚒𝚗𝚝𝚊𝚒𝚗𝚎𝚛 𝚝𝚘 𝚝𝚑𝚒𝚗𝚔 𝚊𝚋𝚘𝚞𝚝 𝚝𝚑𝚎 𝚛𝚘𝚕𝚎 𝙳𝚅𝙲𝙻𝚒𝚟𝚎 (or even DVC API ?) 𝚝𝚊𝚔𝚎𝚜 𝚒𝚗 𝚊 𝚏𝚊𝚜𝚝-𝚝𝚛𝚊𝚌𝚔 𝚜𝚌𝚎𝚗𝚊𝚛𝚒𝚘, 𝚊𝚗𝚍 𝚙𝚛𝚒𝚘𝚛𝚒𝚝𝚒𝚣𝚎 𝚍𝚘𝚌𝚜 𝚊𝚌𝚌𝚘𝚛𝚍𝚒𝚗𝚐𝚕𝚢.

Prioritizing Integrations

Integrations is a section with its own importance in docs in B , thing that has proven important when including a tool in a fast-track scenario. In DVC, I have to go to DVCLive > ML Frameworks

𝙲𝙾𝙽𝙲𝙻𝚄𝚂𝙸𝙾𝙽: 𝚝𝚑𝚎 𝚌𝚘𝚗𝚝𝚛𝚒𝚋𝚞𝚝𝚘𝚛 𝚛𝚎𝚌𝚘𝚖𝚖𝚎𝚗𝚍𝚜 𝚝𝚘 𝚝𝚑𝚎 𝚖𝚊𝚒𝚗𝚝𝚊𝚒𝚗𝚎𝚛 𝚝𝚘 𝚛𝚎𝚌𝚘𝚐𝚗𝚒𝚣𝚎 𝚒𝚗𝚝𝚎𝚐𝚛𝚊𝚝𝚒𝚘𝚗𝚜 𝚊𝚜 𝚙𝚊𝚛𝚝 𝚘𝚏 𝚝𝚑𝚎 𝚏𝚊𝚜𝚝-𝚝𝚛𝚊𝚌𝚔 𝚜𝚌𝚎𝚗𝚊𝚛𝚒𝚘, 𝚊𝚗𝚍 𝚙𝚛𝚒𝚘𝚛𝚒𝚝𝚒𝚣𝚎 𝚊𝚌𝚌𝚎𝚜𝚜 𝚊𝚌𝚌𝚘𝚛𝚍𝚒𝚗𝚐𝚕𝚢.

[SoyGema]

Current user journey for Model Registry

The goal of the following comment is to draft two diagrams comparing the accesibility (number of clicks) that a user must fo to find the useful code snippet for their project within the context of Model Registry. It might serve as an schema to draft user journey from idea to code snippet. Initial page : docs Final page : docs page including code snippet

B analysis

Results : 1 or two clicks to the code

Diagram that shows the story for a user accessing model registry in B. The user can access from QuickStart and from Search bar , in 1 or 2 clicks they are in Model registry able to access the code snippet. Beyond the code, the user can find links to getting Started video and End-to-End guide. The Model Registry page seems to be the place to make a decision , including code and other links

flowchart TD
    
    SE[Search Bar] -->|Model Registry| B(Model Registry)
    
    DG[Developer Guide]
    A[QuickStart] -->|Quick Start Docs| B(Model Registry)
    API[API Reference]
    TUT[Tutorials]
    
    B --> C{Let me think}
    C -->|How it works| D[CODE SNIPPET]
    C -->|Get Started| E[Video Link Quickstart]
    C -->|Walkthrough| F[End-to-end Guide]

DVC Analysis

Results : 4 or 5 clicks to the code , knowing the path, and TBH , I really don´t know if I´m in the right place

The user must search in the bar, then go to the Model Registry Info, then go to Studio Model Registry, then to Add models to registry, then to Live.log_artifact. Please let me know if there is a quicker path for these things. I have add a "let me think" in DVC in each moment that I have to stop to go where I was supposed to, I felt I had some sort of paralysis-for-analysis user experience.

flowchart TD
    
    SE[Search Bar Lateral] -->|Model Registry| B(Model Registry)
    
    UG[User Guide]
    GS[Get Started]
    UC[Use Cases] -->|Model Registry| B(Model Registry Intro)
    CR[Command References]
    I[Info]
    
   B --> C{Let me think} 
   C --> SM(Studio Model registry)
   C --> D(On top of Git)
   C --> E(Versions)
   C --> SM(Studio Model registry)


   SM --> SM2{Let me think} 

   SM2 --> F(Add models to registry)
   SM2 --> H(Register New Versions)
   SM2 --> K(Assign stages to models)
   SM2 --> L(...)

   F --> SM3{Let me think} 

   SM3 --> Dvc(dvc.yaml)
   SM3 --> Dvc2(dvclive)
   SM3 --> Dvc3(Live.log_artifact CODE SNIPPET)

Hey. Hope this can visualize how many steps the user might have to take into account to reach the desired destination, as well as the cognitive load they shall take for this task. I learned some things about diagraming thanks to this discussion, so thanks for the opportunity to contribute! CONCLUSION : the tool 2x the number of clicks WRT other experimentation platforms