Dvc.org: docs: "definitive" organization

[dmpetrov]

UPDATE: Jump to https://github.com/iterative/dvc.org/issues/144#issuecomment-662754116

---

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 https://github.com/iterative/dvc.org/issues/144#issuecomment-584441916 further below

[Dhiraj240]

@dmpetrov I am looking to contribute to the project Improving and expanding User Guide in this upcoming Google Season of Docs 2019. I came here just after the organisations were announced, I already have experience with the opensource organisations. You can see my GitHub profile and Gitlab profile: https://gitlab.com/Dhiraj240?nav_source=navbar
May I know on how to get started with this project so that I will be able to submit a proposal during the proposal period. I found your discord channel for communication.

[dmpetrov]

@Dhiraj240 thank you for your interest! Yeah, Discord is a better place to discuss. I'm seeing you have already started.

[Dhiraj240]

First, I will work on some issues by this week then after that please guide me. On a weekly basis, I will solve issues. :smile:

[dmpetrov]

Awesome!

[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:

• [x] #425 Absorb Understanding DVC into existing sections
• guide: extract part of config cmd ref into the user guide #340
• [x] #1035 merge doc parts into super sections?
• [x] consider https://github.com/iterative/dvc.org/issues/144#issuecomment-559258190 above (avoid 4 levels)
• [x] 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 #731. HIDDEN in #1581
  > - [x] Some of these movements will require redirects, at least for some time.

[VANRao-Stack]

Other general doc structure changes:

...

I have created a pull request for absorbing the understanding DVC section. Please take a look at it and let me know if there are any changes that I may need to bring about.

[jorgeorpinel]

@VANRao-Stack thanks, I will check it out. You are also involved with https://github.com/iterative/dvc.org/issues/614#issuecomment-630561304 though, please pick one issue to focus on for now and let us know.

---

UPDATE: I know this issue is marked as good-first-issue and thanks for taking the initiative but I think this is kind of an epic with many subtasks, some of which are good first issues:

• The general reorg of User Guide as described in the description
• The other related tasks listed in https://github.com/iterative/dvc.org/issues/144#issuecomment-584441916

Your PR is a good start but please focus on a single subtask to make this more manageable.

[jorgeorpinel]

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

Yes, I think it still relevant. We still don't have a good intermediate structure for the UG.

So is the intention of this ticket to figure out the most efficient way to organize our current and future docs in a sustainable way? A kind of "ultimate solution" to docs structure? (If so I can update the issue's title and desc.) Cc @shcheklein @dmpetrov

I think for that we would need to analyze the website traffic, search results, conversions, etc. to make sure the stuff we put close to the surface is the most needed, and to determine which things can get buried or even hidden (no nav entry), even deleted (left for blog posts and support channels to cover).

[jorgeorpinel]

Here's an interesting framework to consider, brought up by @shcheklein: https://documentation.divio.com/introduction/

documentation needs to include and be structured around its four different functions: tutorials, how-to guides, technical reference and explanation. Each of them requires a distinct mode of writing.