docs: Major DVC 1.x discrepancies

[jorgeorpinel]

Mission critical

• Get Started! See get-started: rewrite it (reach "next level") for user interaction #599 (comment) - Ivan is on it update get-started to 1.0 example-repos-dev#14,
• Installation
• dvc add — mainly .dvc file examples cmd ref: dvc add 1.0 update #1411 + merge cmd: pending plots changes by 1.0 release #1414
• DVC-file guide(s) and maybe cache guide - included in user guide: DVC Files and Directories - 1.0 updates #1370
• dvc run PR cmd ref: dvc run 1.0 update #1420 + merge docs: use --external for add/run #1387
• DVC-file guide(s) and maybe cache guide - included in user guide: DVC Files and Directories - 1.0 updates #1370
• document dvc.lock in user guide (see user guide: document dvc.lock (DVC 1.0) #1422) - user guide: dvc.lock section of Files & Dirs #1448
• dvc metrics - metrics: 1.0 update #1360
• dvc plots - Regular updates & plots 1.0 update #1382

Finally

• document run cache? (guide: document run-cache #1289) [tmp] Run cache (1.0) #1464 guide: introduce Basic Concepts guide #1655 (Will happen when experiments are more stable)
• BLOCKER: Figure out auto linking for dvc.yaml and .dvc files to avoid manual management of hundreds of instances (see basic concepts: pipeline stages #1431). - Add functionality to link arbitrary strings in code blocks #1576
• NEW: Address term: simplify multiple mentions about dvc.yaml + dvc.lock + .dvc files #1663 to simplify dvc.yaml/lock and .dvc file mentions (extracted)
• Remove term Dvcfile (see term: stop using Dvcfile #1445)
• • Full sync of cmd ref usage strings and option names (see dvc: check all command usage and options vs docs after main 1.0 release dvc#4024)

Next priorities

• Review all .dvc file examples throughout docs (in YAML code blocks) — note we require YAML 1.2 (se Move to yaml1.2 dvc#4415 and Document that YAML files are expected to be in YAML1.2 #1764) - Review all dvc add examples throughout docs #1605 #1608,
• ^ Also push/pull examples
• Review DVC cache info everywhere, especially in the internal files/dirs guide.
• Replace all instances of term "DVC-file(s)" 😱 as well as "stage file(s)". Use dvc.yaml and/or dvc.yaml as appropriate. (Review stage concept itself, see term: stop using "DVC-file" and "stage file" #1366) - 'DVC-file(s)' replaced with '.dvc file(s)' #1372 + being addressed in guide: update old links to DVC Files and review related terms (prep for dvc.yaml 2.0) #2047 (comment) (not so relevant anymore though)
• Update/remove Katacoda courses accordingly (e.g. fix pipeline getting started documentation and katakoda don't match  #1586, see also rewrite interactive tutorials #1400, ui: add interactive tutorial links to the appropriate pages #670) Not 1.x related
• Update all other command references 😱 (make a list of which ones are pending first...) e.g. cmd ref: improvements to params and 1.0 update! #1456, cmd ref: status: ignoring cache that is not in local cache nor in remote #1701 Extracted to cmd refs: Updates per 1.x #1824
• Review all dvc add examples throughout docs. Avoid having to include the command output unless it's important given the context, definitely don't include progress bars - Review all dvc add examples throughout docs #1255 #1605, Review all dvc add examples throughout docs #1605 #1608
• Let's create a list of places where the concept of stage file(s) and dvc run/checkout/repro are used - docs: List instances of stage file concepts, dvc run/checkout/repro for example review and update to 1.0 #1743:
  We should review all those docs to make sure the use of dvc run/etc and YAML examples are updated to 1.0
• Update dvc repro - repro: 1.x update #1572
• dvc pipeline -> dvc dag docs: replace dvc pipeline with dvc dag #1383 Need to update pipeline links, for now they just redirect to dag. - pipeline: links and examples update for 1.x #1584
• Pending target argument updates (see cmd: update pending target arg descriptions #1574)
• Review all dvc run examples throughout docs Extracted to cmd refs: Updates per 1.x #1824
• Double check all the bullets in 1.0.0 pre-releases/candidates in https://github.com/iterative/dvc/releases [a0, a1, etc.] (at least up to a7)

[pared]

@jorgeorpinel do you keep track of which .dvc examples are being done throughout the code? if there is some list, maybe we could help?

[jorgeorpinel]

Not keeping track of that at the moment @pared but they're all up for grabs! Thanks 🙂

[jorgeorpinel]

document run cache! - draft by @efiop?

Hi Ruslan, any chance the engineering team will be able to submit a draft for this soon? Thanks

[efiop]

@jorgeorpinel Run cache doesn't have much sense on itsown. We will likely describe it when experiments are ready. You could remove that checkbox from this ticket and reopen #1289 , since it is not going to happen very soon.

[jorgeorpinel]

Right, we don't need a stand-alone document for it but it should be mentioned at least in a few places like run and repro. It's definitely a major discrepancy between the released DVC version and the published docs though. Let's continue the conversation in #1289 (I added it to the checkbox and removed your mention for now). Thanks

[jorgeorpinel]

Update all other command references 😱 (make a list of which ones are pending first...)

@imhardikj can you work on that list please? You can extract this one to it's own epic issue with check boxes for pending commands. add, run, metrics? (see #1175), and plots? (see #1800) were taken care of per this issue. We also recently updated move, and I did some others in recent weeks but can't remember which ones. Also look in the existing issues please, as some of them have a ticket e.g. version (#1635) which is an easy one you can take care of soon.

A high priority one would be status for example, and BTW there's code samples of this command in many other places (same for other commands) so that's something we also need to check for updates, as some of those examples may be outdated — could be a separate epic though...

2 issues I found that could probably be merged into the new epic you'll create: #404, #1574 (but there's probably more). Thanks

[jorgeorpinel]

I've reviewed all the pending items and checked most of it. Only a few are left which were extracted to other issues/PRs (mainly #2026) so I'm closing this 🎉

Many thanks to everyone who helped here, especially @imhardikj !