README rewrite (+ CONTRIB updates) #1816

jorgeorpinel · 2022-06-02T03:30:47Z

May be easier to review in its branch: https://github.com/iterative/vscode-dvc/tree/readme#readme

Fix DVC logo img. hack 👇🏼 README rewrite (+ CONTRIB updates) #1816 (review)
Reconsider features vs. advantages lists? README rewrite (+ CONTRIB updates) #1816 (review) 👇🏼 (context)
Move the banner to a side next to title and badges? 👇🏼 README rewrite (+ CONTRIB updates) #1816 (review)
EXTRACTED to readme: float banner to a side? #1937.

+ fancy note

README.md

per #1816 (review)

per iterative/dvc.org#2443 (comment)

README.md

dmpetrov

An intro (value-prop) is needed

dmpetrov · 2022-06-05T04:54:50Z

README.md

-about the extension. Feel free to reach out in this repository's
-[issues](https://github.com/iterative/vscode-dvc/issues) or via any of the other
-existing [support channels](https://dvc.org/support).
+This [extension] integrates [DVC features] right into the popular [VS Code IDE],


Ideally, the readme should start with value-proposition (not too DVC specific) with following competitive advantages (can be specific). Examples (Why TPI/MLEM? is competitive advantages):

https://github.com/iterative/terraform-provider-iterative

https://github.com/iterative/mlem

Ivan just added value-proposition & competitive advantages in the beginning of this doc:
https://docs.google.com/document/d/10THN0WwvPaDOAnmWd37xMOSWftJrUSIPlA2m0iHGDNI/edit#

PS: It is the 1st iteration (please suggest changes) but it gives an idea how to describe the product.

Ideally, the readme should start with value-proposition (not too DVC specific)

I thought the value prop was that it brings DVC into VSC 😅

But I think you're saying that the value is that of the parts of DVC included in the extension + being able to use them visually in the IDE... ⏳

with following competitive advantages (can be specific). Examples (Why TPI/MLEM? ...

We discussed that format and I thought we agreed that those 2 lists (features vs. advantages) tend to be redundant (probably OK for TPI but I'm still not sure about MLEM).

Anyway, I'll go with that for now so we can move on.

https://docs.google.com/document/d/10THN0WwvPaDOAnmWd37xMOSWftJrUSIPlA2m0iHGDNI/edit# per #1816 (comment)

README.md

jorgeorpinel · 2022-06-14T07:46:38Z

we need animations/images for the major blocks

@shcheklein there's an overview gif on top now, and I added a screenshot of the Get Started psge. Other than that I fell like it may become unreadable and too long with images for every block. The walkthrough and actual docs (focusing on that next) can have more pics, I think.

mattseddon · 2022-06-14T08:48:18Z

README.md

@@ -1,31 +1,116 @@
+![banner](https://raw.githubusercontent.com/iterative/vscode-dvc/main/extension/resources/banner.svg)


Have to replace this with a png or run into this build error:
ERROR SVGs are restricted in README.md; please use other file image formats, such as PNG: https://raw.githubusercontent.com/iterative/vscode-dvc/main/extension/resources/banner.svg.

I will fix when I get back in a couple of hours.

😵‍💫

per #1816 (review)

jorgeorpinel · 2022-06-14T09:13:18Z

I think we should merge this to sanity check it live before the release. We can still fix things after merging this PR.

p.s. ignore Restyled for now, it's acting strange. Format is fine rn.

mattseddon · 2022-06-14T09:55:49Z

I think we should merge this to sanity check it live before the release. We can still fix things after merging this PR.

p.s. ignore Restyled for now, it's acting strange. Format is fine rn.

I'll fix the SVG => png then merge

mattseddon

Going to merge this, will sanity check what is in main and then push it out to the marketplace. We can try and get another iteration through when SF comes back online in a few hours

mattseddon · 2022-06-14T10:22:10Z

Unable to merge:

mattseddon · 2022-06-14T10:43:57Z

README.md

+  `HEAD` commit) as well as manage new and existing data from here.
+- Adds a brand-new new **[DVC View]** (<img
+  src="https://raw.githubusercontent.com/iterative/vscode-dvc/main/extension/docs/dvc.png"
+  alt="DVC logo" style="height: 1em;"/> icon in the Activity Bar) with panels to


looks like this styling doesn't work for the in-app content

fixed this by changing from style to height.

mattseddon · 2022-06-14T10:58:02Z

README.md

+- Includes a DVC channel for the _Output_ panel (useful for
+  [debugging](#debugging)).
+
+[dvc tracked]: extension/resources/walkthrough/tracked-explorer.md


All of these relative links need to get changed to the github hosted ones or they won't work in product either

Used absolute paths for all of these links because viewers could be:

In Github.

In the marketplace.

In VS Code.

codeclimate · 2022-06-14T11:37:21Z

Code Climate has analyzed commit b0fa7ab and detected 0 issues on this pull request.

The test coverage on the diff in this pull request is 100.0% (85% is the threshold).

This pull request will bring the total coverage in the repository to 96.6% (0.0% change).

View more on Code Climate.

jorgeorpinel · 2022-06-14T15:03:36Z

README.md

-  [Install the DVC extension for Visual Studio Code](https://code.visualstudio.com/docs/editor/extension-gallery).
- **Step 3.** See Walkthrough.
+Run, compare, visualize, and track machine learning experiments right in VS
+Code. This extension uses [DVC](https://dvc.org/), an open-source data


Make external links open in a new tab by default? This is auto-applied in the VS Code Marketplace.

jorgeorpinel · 2022-06-14T15:04:02Z

README.md

+[data management]: https://dvc.org/doc/start/data-management
+[free course]: https://learn.iterative.ai/
+
+<!-- [learn more]: extension/resources/walkthrough/dvc-learn-more.md -->


jorgeorpinel · 2022-06-14T15:48:33Z

README.md

+  https://dvc.org/doc/user-guide/experiment-management/experiments-overview
+[data versioning]: https://dvc.org/doc/use-cases/versioning-data-and-model-files
+
+## Quick start


Add a ToC? Unlike in GH, https://marketplace.visualstudio.com/items?itemName=Iterative.dvc doesn't auto-generate one nor does it add 🔗 anchors per header.

jorgeorpinel · 2022-06-14T16:46:34Z

README.md

+[dvc view]:
+  https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/view-container.md
+[experiments]:
+  https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/experiments-table.md
+[plots]:
+  https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/plots.md
+[command palette]:
+  https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette
+[dvc tracked]:
+  https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/dvc-tracked-files.md
+[synchronize]: https://dvc.org/doc/start/data-management#storing-and-sharing
+[dvc panel]:
+  https://github.com/iterative/vscode-dvc/blob/main/extension/resources/walkthrough/dvc-tracked-files.md


Change resources/walkthrough links for proper docs? Rel. iterative/dvc.org#3663

jorgeorpinel force-pushed the readme branch 3 times, most recently from ee04761 to f3b6815 Compare June 2, 2022 03:37

readme: make intro = value prop +

9a3b54e

+ fancy note

jorgeorpinel force-pushed the readme branch from 015b208 to 9a3b54e Compare June 2, 2022 03:40

jorgeorpinel mentioned this pull request Jun 2, 2022

READMEs vs Docs iterative/dvc.org#2443

Closed

8 tasks

mattseddon reviewed Jun 2, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

jorgeorpinel added 2 commits June 1, 2022 22:43

readme: spave between VS and Code

9258493

per #1816 (review)

readme: reorg existing content per

7a089a1

per iterative/dvc.org#2443 (comment)

jorgeorpinel force-pushed the readme branch from 304599d to 7a089a1 Compare June 2, 2022 04:52

jorgeorpinel added 2 commits June 1, 2022 23:59

readme: add features list

9d21977

readme: extend/fix/link other parts of the structure

249d88e

jorgeorpinel commented Jun 2, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

jorgeorpinel commented Jun 2, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

jorgeorpinel commented Jun 2, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

jorgeorpinel added the documentation label Jun 2, 2022

jorgeorpinel force-pushed the readme branch from e6644f7 to e74eb79 Compare June 2, 2022 06:51

jorgeorpinel commented Jun 2, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

jorgeorpinel force-pushed the readme branch from e74eb79 to 83babfc Compare June 2, 2022 06:55

readme: fix DVC icon

35aa202

jorgeorpinel force-pushed the readme branch from 83babfc to 35aa202 Compare June 2, 2022 06:57

jorgeorpinel self-assigned this Jun 2, 2022

dmpetrov reviewed Jun 5, 2022

View reviewed changes

This comment was marked as resolved.

Sign in to view

jorgeorpinel mentioned this pull request Jun 7, 2022

Reset workspace: why? #1850

Closed

1 task

jorgeorpinel added 2 commits June 7, 2022 04:08

readme: value prop edited from

6dc30f6

https://docs.google.com/document/d/10THN0WwvPaDOAnmWd37xMOSWftJrUSIPlA2m0iHGDNI/edit# per #1816 (comment)

Merge branch 'main' into readme

2f9ccd1

jorgeorpinel commented Jun 7, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

dberenbaum reviewed Jun 7, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

shcheklein reviewed Jun 8, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

jorgeorpinel requested a review from shcheklein June 14, 2022 07:46

mattseddon reviewed Jun 14, 2022

View reviewed changes

jorgeorpinel added 2 commits June 14, 2022 04:01

Merge branch 'main' into readme

e8c681e

readme: move images back to extension/docs/ foler

d099f31

per #1816 (review)

restyled-io bot mentioned this pull request Jun 14, 2022

Restyle README rewrite (+ CONTRIB updates) #1890

Closed

swap banner to png

75e883f

mattseddon force-pushed the readme branch from 946f48f to 75e883f Compare June 14, 2022 10:11

mattseddon approved these changes Jun 14, 2022

View reviewed changes

mattseddon enabled auto-merge (squash) June 14, 2022 10:20

mattseddon disabled auto-merge June 14, 2022 10:21

replace outdated walkthrough screenshot

4aadbd3

restyled-io bot mentioned this pull request Jun 14, 2022

Restyle README rewrite (+ CONTRIB updates) #1891

Closed

mattseddon reviewed Jun 14, 2022

View reviewed changes

mattseddon added 2 commits June 14, 2022 21:08

update style of inline dvc png so it does not look bonkers

38bb119

(fixup) use absolute links for the marketplace and in product

b0fa7ab

restyled-io bot mentioned this pull request Jun 14, 2022

Restyle README rewrite (+ CONTRIB updates) #1892

Closed

shcheklein approved these changes Jun 14, 2022

View reviewed changes

shcheklein merged commit 2f6b3cb into main Jun 14, 2022

shcheklein deleted the readme branch June 14, 2022 12:31

jorgeorpinel commented Jun 14, 2022

View reviewed changes

jorgeorpinel mentioned this pull request Jun 22, 2022

readme: float banner to a side? #1937

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README rewrite (+ CONTRIB updates) #1816

README rewrite (+ CONTRIB updates) #1816

jorgeorpinel commented Jun 2, 2022 •

edited

Loading

dmpetrov left a comment

dmpetrov Jun 5, 2022

dmpetrov Jun 5, 2022 •

edited

Loading

jorgeorpinel Jun 7, 2022 •

edited

Loading

jorgeorpinel Jun 8, 2022 •

edited

Loading

This comment was marked as resolved.

jorgeorpinel commented Jun 14, 2022 •

edited

Loading

mattseddon Jun 14, 2022

mattseddon Jun 14, 2022

jorgeorpinel commented Jun 14, 2022 •

edited

Loading

mattseddon commented Jun 14, 2022

mattseddon left a comment

mattseddon commented Jun 14, 2022

mattseddon Jun 14, 2022

mattseddon Jun 14, 2022

jorgeorpinel Jun 14, 2022

mattseddon Jun 14, 2022

mattseddon Jun 14, 2022

jorgeorpinel Jun 14, 2022

codeclimate bot commented Jun 14, 2022

jorgeorpinel Jun 14, 2022

jorgeorpinel Jun 14, 2022

jorgeorpinel Jun 14, 2022

jorgeorpinel Jun 14, 2022

		@@ -1,31 +1,116 @@
		![banner](https://raw.githubusercontent.com/iterative/vscode-dvc/main/extension/resources/banner.svg)

README rewrite (+ CONTRIB updates) #1816

README rewrite (+ CONTRIB updates) #1816

Conversation

jorgeorpinel commented Jun 2, 2022 • edited Loading

dmpetrov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmpetrov Jun 5, 2022 • edited Loading

Choose a reason for hiding this comment

jorgeorpinel Jun 7, 2022 • edited Loading

Choose a reason for hiding this comment

jorgeorpinel Jun 8, 2022 • edited Loading

Choose a reason for hiding this comment

This comment was marked as resolved.

jorgeorpinel commented Jun 14, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorgeorpinel commented Jun 14, 2022 • edited Loading

mattseddon commented Jun 14, 2022

mattseddon left a comment

Choose a reason for hiding this comment

mattseddon commented Jun 14, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codeclimate bot commented Jun 14, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorgeorpinel commented Jun 2, 2022 •

edited

Loading

dmpetrov Jun 5, 2022 •

edited

Loading

jorgeorpinel Jun 7, 2022 •

edited

Loading

jorgeorpinel Jun 8, 2022 •

edited

Loading

jorgeorpinel commented Jun 14, 2022 •

edited

Loading

jorgeorpinel commented Jun 14, 2022 •

edited

Loading