Closed SaiedKazemi closed 3 years ago
Sorry, I didn't mean to impose my choice by adding $
to the commands. I just noticed that docker-compose version
had $
and added it to the rest for consistency (please feel free to remove them).
README.md, line 26 at r1 (raw file):
One of the things that we should document as part of our "conventions docs" to be helpful is "typical development environment." I use VSCode for most of my work, with a number of extensions, including "markdownlint". I've come to rely on this linter to tell me what's helpful or not in markdown docs. I've found that it does a good job of keeping the text readable whether it's generated output (e.g. html) or in it's raw text format. In this case, `markdownlint` cares about two cases where the `$` is present for `sh` text blocks. * When the command uses `$` it should show output. For example: `MD014/commands-show-output: Dollar signs used before commands without showing output` * When the command does not use `$` it is much easier for users following along to copy/paste the command. Because this README is structured as a HOWTO, I suggest leaving the commands without `$`. (I personally prefer HOWTOs that make it easy to copy the commands I'm supposed to run) If you prefer to keep the `$`, then I think we should use the guidance from markdownlint and include some output in the example.
Thanks for the context. It's now clear why some commands have $
and some don't. I like this style and suggest that we all adopt it (although we use different development environments).
This change is