update dev container instructions

[reubenmiller]

Signed-off-by: Reuben Miller reuben.d.miller@gmail.com

Proposed changes

Update VSCode dev container instructions after review from @albinsuresh

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Improvement (general improvements like code refactoring that doesn't explicitly fix a bug or add any new functionality)
• Documentation Update (if none of the other choices apply)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Paste Link to the issue

Checklist

• I have read the CONTRIBUTING doc
• I have signed the CLA (in all commits with git commit -s)
• I ran cargo fmt as mentioned in CODING_GUIDELINES
• I used cargo clippy as mentioned in CODING_GUIDELINES
• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if appropriate)

Further comments

[albinsuresh]

A general comment for future reference: It is a common markdown practice to keep each sentence in a paragraph on individual lines rather than having a single line with multiple sentences in it. This helps while giving update suggestions as a reviewer and also helps in keeping the diffs small and localised to a single line.

[reubenmiller]

A general comment for future reference: It is a common markdown practice to keep each sentence in a paragraph on individual lines rather than having a single line with multiple sentences in it. This helps while giving update suggestions as a reviewer and also helps in keeping the diffs small and localised to a single line.

Interesting point, I've never thought about it much. But overall, I don't like long paragraphs in technical (online) documents as it makes it very hard to read (imho). If a sentence can stand on its own, then I usually put it in its own paragraph.

But generally the advantages I see for short paragraphs are:

• easier to read and more likely someone is actually going to read it (and not skip the last half of it)
• easier to reference when talking with someone, "hey the info is in, section x, paragraph 2"
• easier to comment / cleaner git diffs (from your feedback)

Here is a link to technical doc writing which I just found...notice there are a lot of short paragraphs ;)
https://www.freecodecamp.org/news/how-to-write-a-great-technical-blog-post-414c414b67f6/

[albinsuresh]

A general comment for future reference: It is a common markdown practice to keep each sentence in a paragraph on individual lines rather than having a single line with multiple sentences in it. This helps while giving update suggestions as a reviewer and also helps in keeping the diffs small and localised to a single line.

Interesting point, I've never thought about it much. But overall, I don't like long paragraphs in technical (online) documents as it makes it very hard to read (imho). If a sentence can stand on its own, then I usually put it in its own paragraph.

But generally the advantages I see for short paragraphs are:

• easier to read and more likely someone is actually going to read it (and not skip the last half of it)
• easier to reference when talking with someone, "hey the info is in, section x, paragraph 2"
• easier to comment / cleaner git diffs (from your feedback)

Here is a link to technical doc writing which I just found...notice there are a lot of short paragraphs ;) https://www.freecodecamp.org/news/how-to-write-a-great-technical-blog-post-414c414b67f6/

With that comment I wasn't trying to encourage longer paragraphs at all. I was just suggesting that single line paragraphs(even smaller ones) are not very diff/review friendly unless they are very very small. So, even when I have smaller paragraphs, I try to put each sentence on individual lines as follows:

para1 sent1.
para1 sent2.
para1 sent3.
...

para2 sent2
para2 sent2
... and so on

...so that when I have to suggest a change for para1 sent2, the diff will only show that line has changed rather than the entire paragraph.