docs: misc content & guide updates

[casperdcl]

• misc copyediting mainly of /doc/start/
• add/update/use some <abbr>s
• fixes docs: wrong use of diff highlighting + indentation problem #1761

[jorgeorpinel]

Please split into 2 or hopefully more PRs, it's too big 🙂 Thanks!

I didn't review the Get Started changes yet, just the concepts pages.

[casperdcl]

Please split into 2 or hopefully more PRs, it's too big 🙂 Thanks!

I thought it would be a bit overwhelming. This PR is only about 20% of the start of the basic documentation copyediting I'm planning before moving on to high-level reorganising and then major new content.

Good job I stopped myself from including the remaining 80% of the "basic start" in this PR :)

You may find the "Viewed" checkbox useful when reviewing multi-file PRs.

[iesahin]

You like your dashes :)

I read the PR and it's a nice touch. Thank you very much.

BTW, the dataset/code in the GS section will be updated. We'll probably use MNIST dataset for a new example-get-started. Most of the content will need another revision then. You can keep this in mind when revising/updating.

[casperdcl]

You like your dashes :)

I actually don't like them but was simply aiming for consistency first (dashes were already used in more places than hyphens). The "correct" way really is double hyphen -- which is auto-rendered as a dash — but that's for a separate PR :)

[jorgeorpinel]

thought it would be a bit overwhelming. This PR is only about 20% of the start of the basic documentation

Trust me I know all about how quickly docs PRs can grow. It's a constant struggle to find the right balance. In this case I perceived the Get Started changes to have repeating patterns so that group of changes I think could've been a PR. Then there were the basic concepts which could've been another. Then all the other misc. changes seemed OK for a PR (which would be merged at this point).

We don't have a well defined rule yet, but let's work on it together. The one thing I can tell you is we prefer the problem of having many PRs to having big PRs!

You may find the "Viewed" checkbox useful when reviewing multi-file PRs.

The technical problem with large docs PRs comes when the review goes on for many rounds with dozens of comments in each one. GH starts hiding some content (resolved or not) which makes navigating the PR page quite difficult.

double hyphen -- which is auto-rendered as a dash

😮 I didn't realize this, yeah def better! I actually have a special keyboard shortcut just for m-dash 😆

[jorgeorpinel]

Review for content/docs/start/data-and-model-access.md. Some comments can probably be generalized to the remaining files, so I'll review the others when this one has been addressed 👇 Thanks!

[jorgeorpinel]

Review of content/docs/start/data-and-model-versioning.md 🙌 Thanks!

[jorgeorpinel]

Please make a separate issue/PR if needed to introduce the "storage location" term throughout docs, as we have an established way to refer to "remote storage" and "DVC remote(s)" ATM. For now:

[jorgeorpinel]

OK! Here's the review for https://dvc-org-docs-misc-fixes-seg0k4.herokuapp.com/doc/start/data-pipelines. As you can see each page has a long review, which is why I still think we should split the PR. It's getting unmanageable at this point.

Please: Each GS page should be a PR, including one to address this review (so we can wrap up all the previous comments and merge this one), then one for Metrics/Plots/Params, and one for Experiments. Keep in mind you're editing a very important section with lots of strategic words, passages, etc. Even sentence lengths were designed. Each page took weeks to finalize. So we have to be extra careful.

And again, please try to minimize style/tone/subjective changes in the remaining GS pages based on previous reviews.

Thanks @casperdcl, we're getting there and many of the edits here are going to improve the readability a lot!

[jorgeorpinel]

Seems like @dberenbaum is busy. These are copy edits anyway so here's the review of the one last file pending. Thanks!

[jorgeorpinel]

LGTM 🚀

[jorgeorpinel]

Kaboom.