Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

guide: required software to run docs local dev (contrib) for Windows #2692

Merged
merged 14 commits into from
Oct 14, 2021
29 changes: 19 additions & 10 deletions content/docs/user-guide/contributing/docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ the documentation content, or (rare) changes to the JS engine we use to run the
website.

In case of a minor change, you can use the **Edit on GitHub** button to open the
source code page. Use thethe Edit button (pencil icon) to edit the file
in-place, and then **Commit changes** from the bottom of the page.
source code page. Use the Edit button (pencil icon) to edit the file in-place,
and then **Commit changes** from the bottom of the page.

> Please see our
> [Writing a Blog Post guide](https://dvc.org/doc/user-guide/contributing/blog)
Expand Down Expand Up @@ -59,6 +59,15 @@ formatted and linted as well, which is also ensured by the full setup below.
Make sure you have a recent LTS version of [Node.js](https://nodejs.org/en/)
(`>=12.0.0`, `<=15.x`), and install [Yarn](https://yarnpkg.com/):

> In Windows, you may need to install [Python], [Visual Studio Build Tools], and
iesahin marked this conversation as resolved.
Show resolved Hide resolved
> [Windows SDK] additionally for dependencies.
iesahin marked this conversation as resolved.
Show resolved Hide resolved

[windows sdk]:
https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk/
[visual studio build tools]:
https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019
[python]: https://www.python.org/downloads/

```dvc
$ npm install -g yarn
```
Expand Down Expand Up @@ -140,8 +149,8 @@ Some available variables:

## Doc style guidelines (JavaScript and Markdown)

Some the rules below are be applied automatically by a pre-commit Git hook that
is installed when `yarn` runs (see [dev env](#development-environment)).
Some of the following rules are applied automatically by a pre-commit Git hook
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved
that is installed when `yarn` runs (see [dev env](#development-environment)).

- No trailing white spaces are allowed.

Expand All @@ -164,9 +173,9 @@ is installed when `yarn` runs (see [dev env](#development-environment)).
create a link to that API method automatically. (No need to use `[]()`
explicitly to create them.)

- Markdown: Neither bullet lists nor each item's should be too long (3 sentence
- Markdown: Bullet lists and their items shouldn't be too long (3 sentence
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm, this was correct before though.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was correct but neither/nor is usually for things of the same kind. I simplified the wording.

Copy link
Contributor

@jorgeorpinel jorgeorpinel Oct 14, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unresolving. OK but "something AND something should not" is even stranger language. "And" is positive, "not" is negative. It's confusing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK I updated this...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree on the unrelated changes. PR should be focused (we all do this from time to time though - it's tempting to fix minor things as you go).

In this case though - does it change semantics? The way I read it - they are the same for me. Is it the case where we should have strong opinion on how it's written? My suggestion next time would be - unless it's incorrect, or significantly complicate the meaning - let's avoid discussions like this? wdyt?

Also - let's state how important for you (as a reviewer) this thing is if it's not clear. E.g. minor: blah-blah-blah. So that author could merge even if there are small things unresolved. It's never an intention to solve all minor things I guess.

Copy link
Contributor

@jorgeorpinel jorgeorpinel Oct 14, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My suggestion next time would be - unless it's incorrect, or significantly complicate the meaning - let's avoid discussions like this? wdyt?
Also - let's state how important for you (as a reviewer) this thing is

I agree in general but it can be tricky once something is touched if a question comes up about the change we need to communicate somehow and for a very small PR like this one that can double the merge time. We should completely avoid unrelated changes in small PRs, some copy edits can be thrown in medium/large PRs IMO (as long as they don't make the review process harder).

BTW @iesahin I changed this and merged assuming you don't have a strong opinion (and to get this done) but I tried to address your concern when doing so. We can revisit if needed. Thanks

paragraphs max.) Full sentence bullets should begin with a capital letter and
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved
end in period `.` otherwise they can be all lower case and have no ending
end in period `.`. Otherwise, they can be all lower case and have no ending
punctuation. Bullets can be separated by an empty line if they contain several
paragraphs, but this is discouraged: try to keep items short.

Expand All @@ -193,9 +202,9 @@ We try to use a casual and fun tone in our docs. We also avoid authoritative
language such as "As you can see, clearly this is what happened, of course" etc.
which while good-intentioned, may scare readers off.

We prefer human-friendly language than exact jargon, as long as it's correct,
even if using general terminology. Example: avoid Git jargon such as _revision_
or _reference_, preferring the more basic concept _commit_.
We prefer human-friendly language rather than exact jargon as long as it's
correct. Example: avoid Git jargon such as _revision_ or _reference_, preferring
the more basic concept _commit_.
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

The [command reference](/doc/command-reference) contains some of our most
technical documents where specialized language is used the most, but even there,
Expand All @@ -204,7 +213,7 @@ we use expandable sections for complex implementation details.
Start by writing the essence in simple terms, and complete it with
clarifications, edge cases, or other precisions in a separate iteration.

We use **bold** text for emphasis, and _italics_ for special terms.
We use **bold** text for emphasis and _italics_ for special terms.
iesahin marked this conversation as resolved.
Show resolved Hide resolved

We also use "emoji" symbols sparingly for visibility on certain notes. Mainly:

Expand Down