Add troubleshooting guide

[pared]

Disregard the recommendations below if you use Edit on GitHub button to improve the docs in place.

❗ Please read the guidelines in the Contributing to the Documentation list if you make any substantial changes to the documentation or JS engine.

🐛 Please make sure to mention Fix #issue (if applicable) in the description of the PR. This enables GitHub to link the PR to the corresponding bug and close it automatically when PR is merged.

Thank you for the contribution - we'll try to review and merge it as soon as possible. 🙏

Fixes #871

[shcheklein]

@jorgeorpinel @pared let's create a user guide Troubleshooting section. I don't like this duplication and complication of the command reference. We can create a separate page per error, or for now a single page with expandable blocks or h2 segments.

[jorgeorpinel]

@shcheklein my initial #871 (comment) was

If it will fit in a single paragraph I recommend using existing docs, probably some of the command references. It can be repeated in a few ones wherever it's appropriate.

We have several of these repeated notes, paragraphs, sentences in different docs already, especially command references. It makes sense since there's overlap in functionality or implementation details in many places.

I don't think we need a Common problems section though, since there's only one and can't foresee having others in the immediate future. Maybe just add the paragraph in the bottom of the Description section? Starting with "A known issue..."

[shcheklein]

If it will fit in a single paragraph

It looks like it does not, right? at least it'a big paragraph already :) And it would be an artificial constraint to try to keep error explanations like this very short.

also, this is an edge case, it's not that important to include it into description for all commands (3 places at least?)

We have several of these repeated notes, paragraphs, sentences in different docs already, especially command references.

they are usually small, there are not so many of them, and it might be a problem for some of them that they are repeated. And to my point above - they are usually general enough and highlight some important workflow (like installing S3 with DVC), they do not serve as an explanation of an error code.

I don't think we need a Common problems section though

I like Troubleshooting as the name, someone has used it already in some comment - it makes sense to me :)

can't foresee having others in the immediate future

I can easily add a few :)One of the most commons - what should I do when I get "DVC is busy" message. There will be more and more as we move forward and improve interface.

[jorgeorpinel]

let's create a user guide Troubleshooting section

To be clear, I'm not opposed to this. It's a good option, and just link from these command refs. BTW @pared please notice my other #871 (comment) in the issue:

Maybe also checkout since it can include pull. Consider adding the note in the remote index page too.

@shcheklein:

at least it'a big paragraph already

Indeed, it's a long one even, my shorter version. Would be nicer to split it in 2.

I like Troubleshooting as the name

Yes, I like it too. Or/and Known issues

[shcheklein]

I would say: Known issues and Troubleshooting have different meaning to me. First is about actual existing bugs (and probably our GH issue tracker represents it really well, though it can be complimented with some docs if some issues are not going to be fixed ... ever). Second is about solving troubles - they are not necessarily issues to me.

[jorgeorpinel]

Agree. This file descriptor thing to me sounds like an issue that could have a code solution to me. Not sure though.

[pared]

Agree. This file descriptor thing to me sounds like an issue that could have a code solution to me. Not sure though.

@jorgeorpinel yes, it is solvable, and this change is taking some time because we were discussing it a lot with @efiop and @Suor. Some of the conclusions can be found at
iterative/dvc#2866 and
iterative/dvc#2473

The conclusion was that we want to preserve quite high default value of jobs, and don't want to introduce complicated logic to adjust (only default) jobs value on a single remote (s3). In the future we will probably fix it by retrying after this fail, but that will probably need reorganizing error handling, so it will be bigger than try: except OsError
iterative/dvc#2965

[pared]

@jorgeorpinel @shcheklein I created Troubleshooting User guide section and included @jorgeorpinel suggestion.

[shcheklein]

A few improvement requests.

You also need to update the sidebar.json file to make this section active. See the contributing guide - it should include the instruction, I believe. I would recommend running this locally to test it.

[jorgeorpinel]

yes, it is solvable...

Thanks for all the context @pared! So, my point was that this may not be a "trouble" the way @shcheklein described it, but in fact a "known issue". I think you're confirming this?

[shcheklein]

@jorgeorpinel @pared if agree on it to be a "known issue" then we don't need this doc - let's open ticket in the Github DVC repo with a description, workaround, ETA on solving, etc. I don't think we need document this things. To me the current solution is a first iteration, but a solution - thus I was thinking this documentation makes sense and should be part of the troubleshooting.

[jorgeorpinel]

if agree on it to be a "known issue" then we don't need this doc... I don't think we need extra documentation besides GitHub issue tracker for "known issues" and "known problems" (in a sense that they are actual design bugs, bugs and/or are going to be fixed)

To be or not to be! (A known issue) That is the question. I like the "regular workflow, you just hit bumps" argument but not sure it's accurate. I have to yield to you guys in the end to decide what this thing is. But I think Ivan is right that a fully described issue on GH would be enough for "known issues".

Maybe @efiop or @Suor (mentioned before) have comments on this?

[shcheklein]

regular workflow, you just hit bumps

k, to be more precise :) regular workflow, advanced scenario, setting up it properly. It can be considered somewhat similar to that "slow linking" message we have.

[jorgeorpinel]

Done @pared. See d2293b5 ^

p.s. I went for err.dvc.org/{hdr} -> dvc.org/doc/user-guide/troubleshooting#{hdr} BTW but feel fee to change it as needed.

[pared]

@shcheklein @jorgeorpinel updated the address in docs, also the dvc PR, now it looks like that:

[jorgeorpinel]

updated the address in docs...

Thanks @pared. There's just this one matter to decide definitely on, I think: #875 (review) please weight in if you can 🙂

UPDATE: And this one about 301 vs 302 response codes actually: #875 (review) ... ✔️

[jorgeorpinel]

Shortened nav title to just "Troubleshooting"

See https://dvc-landing-2473-amnjganfpaic8.herokuapp.com/doc/user-guide/troubleshooting

Opened web: enable custom anchor id/href for troubleshooting guide? #922