docs: "definitive" organization

[dmpetrov]

UPDATE: Jump to #144 (comment); E: #144 (comment)

---

We need to add an additional level to the user guide:

1. Basic

• DVC Files and Directories
• DVC File Format
• External Dependencies
• External Outputs
• Update a Tracked File
• Anonymized Usage Analytics

2. Customization

• DVC Shell Autocomplete
• IDE Plugins & Syntax Highlighting
• Development Version
• Contributing

---

UPDATE: See discussion about structure below, and more subtasks in #144 (comment) further below

[jorgeorpinel]

The user guide structure has changed quite a bit since this was opened. Is it still desired?

[shcheklein]

Yes, I think it still relevant. We still don't have a good intermediate structure for the UG. Not sure if it overlaps with some other tickets or duplicates them.

[jorgeorpinel]

OK. I'd just note that to avoid 4 levels (excessive clicking) we'll need to remove the Contributing submenu and just list both contribution guides inside Customization directly.

[shcheklein]

@jorgeorpinel don't consider that split in the ticket description as a final one. It's just an example to illustrate the idea.

[jorgeorpinel]

Other general doc structure changes (each one of these could be a good-first-issue:

• user-guide/get-started: reorganize "Understanding DVC" section #425 Absorb Understanding DVC into existing sections
• guide: extract part of config cmd ref into the user guide guide: extract part of theconfig cmd ref. #340
• docs: consolidate examples and higher level structure #1035 merge doc parts into super sections?
• consider docs: "definitive" organization #144 (comment) above (avoid 4 levels)
• We should also move the Google API Privacy Policy (https://dvc.org/doc/user-guide/privacy) to another location (not really a user guide) and/or consider having it as a link without nav entry (nor in site footer) implementing docs: support items without nav sidebar entry #731. HIDDEN in guide: absorb What is DVC? into other existing docs, et al. #1581

• Some of these movements will require redirects, at least for some time.

[iesahin]

Repeating the questions in https://www.notion.so/iterative/wip-Audiences-ccb7abb9a198476aa0c01581479c5eaf

• Who uses DVC?
• What do they use DVC for?
• How do they use DVC?

The answers to these questions should shed some light on the docs organization. We can't be everything to everyone, so we must select the most obvious audience and make docs organization easier for them.

[jendefig]

@iesahin @jorgeorpinel
While I do agree that organizing docs should be a function of audience, I think the need and request for having workflows isn't an audience question, it's because as the tools have more features, the docs grow and become harder to absorb. (It's a lot to read/take-in). We have to figure out a way to simplify the organization of the docs to seem less overwhelming. All the documentation on commands must be there. It's a question of ingestion and that ingestion experience.

Landing on home page isn't showing a clear BIG picture of where in the ML process DVC fits (solution positioning)
I agree with this one hundred percent. Need a big picture a-ha moment right from the start. And it needs to be a sharable image.

On 1. Are we sure that Use Case is the best term? We should use the language they are coming to us with. I'm curious what terminology was used in @dmpetrov's discussions with the same request. It is interesting that "command-centric" was used in what we both heard, but in what they were looking for instead, what terminology did they use? (What makes sense to our audience?) (Maykon definitely used "workflow")

Also regarding this in particular. Why don't we just crowd source the Community? Ask the question: "To better serve your needs in our docs, we are asking for you to fill in and upvote items in this document (public in Notion?) on what workflows you would like to see covered in our docs. For example, finish the search "How do I _____ ?" (or however we should ask this).

Also from talking to Community members, it seems they go through steps in their usage/adoption. Maybe we need to change the buttons on the main page to these milestones? I want to:
Version my Data
Set up my pipeline
Version my Models
Version my Experiments
Examine my Results
Automate testing

Regarding the "Big picture" image, it would be awesome to be able to click on which section of the process they are dealing with to get to the corresponding docs about our tools. (Yes, I dream big ;) )

On 2. Quick start vs. get started? This would be confusing. Why not Features and Tutorials? with a search capability in each

Not sure about 3 and 4. need more rumination.

[jorgeorpinel]

The top priority should be to have a clear big picture expressed in the home page: e.g. a figure covering the entire ML lifecycle, where DVC comes in, and why that's better.

Other than that, the larger challenge is achieving a docs structure that can fit a lot of content in a way that seems simple and clear. I'm not sure that can be done under a single tree like the navigation menu we have on the left side.

💡 Maybe we need an orthogonal separation by features (mapped to the big picture above) that essentially filter content depending on the focus of each user (similar to the proposed Get Started trails @iesahin has been working on). There would be some overlap in terms of explanation and reference docs, but a single Quick Start one-pager in each one and/or a bit longer Learn "tutorial?" (current G/S pages) + room for more complex tutorials if needed.

On the term "use cases" we can definitely change it to "scenarios", "solutions", "why DVC", or something else. They should probably get out of the Docs section and be proper landing pages instead of the current /features (this has been discussed several times). And in that case we don't even need to name them anything special, they'd just be in custom URL paths like dvc.org/data-versioning .

[iesahin]

What I had in mind talking about "audiences" is that the workflows and expectations of these audiences vary considerably. We don't have a "single basic workflow" as Git may have. DVC's MLOps workflow(s) are considerably different than Data Science workflow(s), and IMO the best way to model this is via answering the "who?" question.

If we start from "who", then it's easier to think about "what do these users do in 80% of their time with DVC?" question that will lead us to specific workflows.

On top of this, we can have several different ways to structure the documents, e.g., longer tutorials vs quick get started. I'd like to have some tests and feedback mechanisms to measure the merits of these before deciding.

[casperdcl]

Maybe we need to change the buttons on the main page to these milestones? I want to:
Version my Data
Set up my pipeline
Version my Models
Version my Experiments
Examine my Results
Automate testing

I like this idea. A popup perhaps linking to relevant "getting started" sections?

[jorgeorpinel]

UPDATE!

I think that this issue is too broad so we may never be satisfied with a definitive plan for this.

Also, the main remaining problem seems to be in the User Guide (book-like explanation content) and we have several "smaller" epics to tackle that. Specifically:

• guide: new DVC Concepts section #550
• guide: Data Management #2856
• guide: Modeling Pipelines #2883
• guide: Experiment Management (phase 2) #2911
• guide: add "Best Practices" #72
• how: new (sub)section (How To's) #899

As well as a few important issues related to the Command Reference:

• guide: extract part of theconfig cmd ref. #340
• guide: extract remote add/modify details from cmd ref. #2866

So we should probably close this, as long as those issues reflect the directions we intend, as described in #144 (comment) above:

Docs now are too command-centric; people can sometimes get lost in the details; unclear where to find the information they need...
0. Landing on home page isn't showing a clear BIG picture;

1. High-level scenarios (use cases)
2. How do we teach the tools? Quick Start
3. Usage Guides (explanations and/or walkthroughs) & References (purpose details, semantics)
4. Everything else? (How-tos, Troubleshooting, etc.)

The only other thing from ☝🏼 that's not covered in the mentioned issues is the home page redesign, but I can create a separate issue for that. WDYT @dmpetrov @shcheklein @casperdcl ? Thanks

---

Edit: there's also a related feature request/discussion:

• Pathfinder #3128

[casperdcl]

I think that this issue is too broad so we may never be satisfied with a definitive plan for this.

to me we can definitely come up with some action points

• are all the scenarios from the OP covered?
• this popup/design idea
• design: draw more attention to search box
• agree on layout (neverending, not as important as above)

[dberenbaum]

@jorgeorpinel and I discussed some of these issues. A summary of some of my takeaways:

• We need to prioritize between changes to:
  • Landing page: DVC home page + updates #3833.
  • Get started: need to discuss plans for "trails," but goal should be address high-level use cases.
  • User guide: we are already working on Added id as props for unique anchor #3413 and guide: make plots guide #3830, so I think it would make sense to prioritize this.
• User guide plans:
  • Split into high-level feature explanations and how-to: each high-level feature can be a section, and how-to can be an additional section with small pages addressing more low-level scenarios (linked from other places to be found),
  • Thoughts on existing pages:
    • Index page: remove?
    • What is DVC: dissolve into some page outside the user guide (and maybe in the home page/outside of docs) - guide: new Overview page #4006
    • Project structure: move this into some "reference" section ("Metafile Schema Reference"?) -- could break reference into CLI, API, and this.
    • How to: keep it at the bottom of the user guide with subpages.
    • Setup GDrive remote: put into data management section of user guide or make into blog post (I prefer the first if we can support it).
    • External Deps/Managing External Data: put into pipelines section of user guide or make them only reachable via links.
    • Running on Windows: put in how to or part of https://dvc.org/doc/install/windows.
    • Troubleshooting/Glossary: leave at bottom of the user guide.
    • Related Technologies: dissolve into some page outside the user guide - guide: new Overview page #4006
    • Anonymized usage analytics: put at bottom of the user guide or make it only reachable via links (I prefer to keep it somewhere so it doesn't look like we are hiding this info).

cc @shcheklein

[shcheklein]

Alternative that I had in Slack (just as an idea):

• What is DVC (move related techs inside it)
• Project Str
• Experiments Mng (Visualzing Plots should be inside)
• Data Management (Remote, Large Data, External Data)
• Troubleshooting
• How to (move Windows inside, may even Google Drive for now)
• Telemetry Policy
• Glossary (I would remove it - I don’t think it’s useful tbh - why do we need it)?

[jorgeorpinel]

What is DVC (move related techs inside it)

Currently, I started disintegrating that one as we didn't see it fitting the goals of the user guide as stated above (high-level feature explanations).

However, 💡 we could turn it into an Overview instead, which would combine its existing Core Features section as well as Related Technologies. That way we take care of 2 birds (from the bullet list above) with one stone.

🐦 🐦 🪨 ☠️ ☠️

[dberenbaum]

#4006 looks like a nice move in the right direction!

Alternative that I had in Slack (just as an idea):

What is DVC (move related techs inside it)
Project Str
Experiments Mng (Visualzing Plots should be inside)
Data Management (Remote, Large Data, External Data)
Troubleshooting
How to (move Windows inside, may even Google Drive for now)
Telemetry Policy
Glossary (I would remove it - I don;’t think it;’s useful tbh - why do we need it)?

Maybe we need an additional Pipelines Mgmt section in addition to Experiments Mgmt and Data Mgmt (esp since we just created this section 😄 )?

[dberenbaum]

Hm, now I see that pipelines is complicating things since pipelines are so tightly coupled to data management.

That could make sense if we position data management as including the pipelines to generate the data 🤔 .

[jorgeorpinel]

Maybe we need an additional Pipelines Mgmt section

We have https://dvc.org/doc/user-guide/pipelines and #2883.

data management as including the pipelines to generate the data

I think that for the get started is OK to cover pipelining basics inside Data Management but the feature set is so rich (and maybe has some non-data-centric uses) that it does deserve a user guide section. We can still mention and link a lot about it from data mgmt pages and vice versa.

[jorgeorpinel]

Glossary (I would remove it - I don’t think it’s useful tbh - why do we need it)?

No strong opinion but I like it. It's at the bottom of the section so it's not in the way either.

p.s. probably the page I visit more from Git docs is https://git-scm.com/docs/gitglossary (but then again I work a lot with wording and definitions).

[jorgeorpinel]

Hi. I believe this was closed with #4011 but it's been here for so long I'm hesitant to press the Close button. WDYT @dberenbaum @shcheklein @casperdcl @dmpetrov ?

See the latest, simplified structure of https://dvc.org/doc/user-guide -- it will never be perfect but we have a working framework now (at least for DVC), I think.

[shcheklein]

Yes, I think we are good to close it for now and iterate on specific tickets.

[dberenbaum]

The definitive organization is complete, never to be touched again 😄

[jorgeorpinel]

"never"