Dvc.org: docs: remove unnecessary index pages that serve as a table of contents

[shcheklein]

Blocked by #738

E.g. https://dvc.org/doc/user-guide/contributing

It'll be very painful to support them. We will need to keep titles up to date, list of them, snippets, etc, etc.

Let's not use pages like this at all or come with a way to generate them automatically.

cc @dashohoxha

[jorgeorpinel]

The point of having them is that we can add some text about the purpose of the section, and summary of each page inside. All of those texts are custom, they don't come from inside any of the other pages. So auto-generating them won't be able to get these same results, so I think the decision is either keep them or remove them. If we don't want to have to maintain them, let's just delete all these index.md files.

[shcheklein]

@jorgeorpinel yep, I don't mean pages that have some unique content or some introductory text. I specifically mean pages https://dvc.org/doc/user-guide/contributing that do not have any new content but repeat the structure. Moreover I really like that page, but I understand that it'll be a nightmare to keep those in sync w/o proper tooling.

[dashohoxha]

Let's not use pages like this at all

I have tried "source": false, on sidebar.json, but it doesn't work (unless it is the top level, like understanding-dvc). Maybe it should be fixed on the engine.

come with a way to generate them automatically

Again this seems like it needs to be fixed on the engine. I could be specified with a field like "source": "auto", or "source": "index",

[dashohoxha]

If we don't want to have to maintain them, let's just delete all these index.md files.

@jorgeorpinel As I said above, currently this is not possible, as it breaks the engine. Maybe this could be regarded as bug too, because I would expect it to work automatically without index pages.

so I think the decision is either keep them or remove them

I agree with @shcheklein , sometimes they are useful, sometimes they are a burden. I think that autogenerating an index page should be the default, unless the "source" is given explicitly, or is specified as false.

[shcheklein]

@dashohoxha

As I said above, currently this is not possible

It should be possible - check understanding DVC and/or changelog sections.

[jorgeorpinel]

yep... I specifically mean pages https://dvc.org/doc/user-guide/contributing

Ah, Ok. Never mind Ivan.

I have tried "source": false, on sidebar.json, but it doesn't work (unless it is the top level, like understanding-dvc)... it breaks the engine. Maybe this could be regarded as bug...

I'm able to reproduce this bug. I would say just delete the index pages and open a separate bug issue @dashohoxha. (We could wait for that fix before merging this PR.) All parent slugs with "source": false should behave like understanding-dvc, that opens Collaboration Issues by default. BTW it should also change the URL to .../collaboration-issues no? (part of the bug report)

I think that autogenerating an index page should be the default...

Automatically generating a list of H2s in child documents when no source field is used for a parent slug is an engine feature that could also be worked on, but separate to the change I suggested above.

[shcheklein]

@jorgeorpinel could you please create a ticket to fix the issue with indexes? Do you want to try to take it? :)

[jorgeorpinel]

Opened #738. So this one is now just to delete all indices as I suggested? Updating title

[shcheklein]

Yep, I would clarify that not all indexes - only those that do not provide any extra value and can be generated in the future.

[jorgeorpinel]

I'm confused, actually. What is the difference between this issue and #738? Seems to me like this one depends on that one at least. We could probably re-merge them?

[shcheklein]

Yeo, this one depends on #738, but they are different anyway. I would keep them separate for simplicity.

[jorgeorpinel]

OK I'm working on this one now. @shcheklein. One question, what about

• https://dvc.org/doc/command-reference/cache,
• https://dvc.org/doc/command-reference/metrics,
• https://dvc.org/doc/command-reference/pipeline, and
• https://dvc.org/doc/command-reference/remote

? They have useful, unique content but I'm not sure the cmd ref is the best place for those explanations. Should we take the opportunity to move them into a new user-guide: "Basic Concepts" (#550)?

UPDATE: Following up in https://github.com/iterative/dvc.org/pull/903#issuecomment-572172797

[jorgeorpinel]

Hmmm. Actually the only other index left that definitely isn't useful in the cmd ref is for tutorials (besides the user-guide/contributing one). See draft PR #903 ^

I'm not sure about https://dvc.org/doc/use-cases or https://dvc.org/doc/user-guide. I'd like to remove them (so we don't have to maintain those bullet lists manually) but they do have some small unique paragraphs explaining the sections, and they forces users to chose the topic they're looking for... Thoughts?

UPDATE: Discussion continues in https://github.com/iterative/dvc.org/issues/727#issuecomment-571407120