ipfs-docs icon indicating copy to clipboard operation
ipfs-docs copied to clipboard

Adding "how to create new page" to `CONTRIBUTING.md`

Open TMoMoreau opened this issue 2 years ago • 3 comments

This PR is in reference to issue #1264

TMoMoreau avatar Sep 28 '22 19:09 TMoMoreau

  • Image optimization came back clean!
  • Vuepress build was successful!

filecorgi avatar Oct 06 '22 18:10 filecorgi

@johnnymatthews @ElPaisano I may still want to add more screenshots or go into more detail about certain things. Let me know what you think.

TMoMoreau avatar Oct 06 '22 18:10 TMoMoreau

@TMoMoreau made some general comments above, might be easier to just talk through them real quick

ElPaisano avatar Oct 07 '22 19:10 ElPaisano

General comment: The vale linter is showing a Flesch Reading Ease score of 68.2, which is pretty good. According to that metric, it means that the document is "easily understood by 13- to 15-year-old students". However, the vale target is 70, which indicates "fairly easy to read".

The score is a function of:

  • the average length of your sentences (measured by the number of words)
  • the average number of syllables per word

I ran markdownlint which, among other things, checks if line length is greater than 80. (this is configurable). I saw a lot of output like:

projects/testFiles/CONTRIBUTING.md:126:81 MD013/line-length Line length [Expected: 80; Actual: 282]
projects/testFiles/CONTRIBUTING.md:131:81 MD013/line-length Line length [Expected: 80; Actual: 107]
projects/testFiles/CONTRIBUTING.md:133:81 MD013/line-length Line length [Expected: 80; Actual: 125]
projects/testFiles/CONTRIBUTING.md:137:81 MD013/line-length Line length [Expected: 80; Actual: 419]
projects/testFiles/CONTRIBUTING.md:139:81 MD013/line-length Line length [Expected: 80; Actual: 208]
projects/testFiles/CONTRIBUTING.md:145:81 MD013/line-length Line length [Expected: 80; Actual: 184]

So, just something to keep in mind. If possible, keep sentences as short as possible, as it will make the overall reading experience easier for most readers. This will also bring the readability score up.

ElPaisano avatar Nov 15 '22 12:11 ElPaisano

markdown-link-check came back clean 💯

ElPaisano avatar Nov 15 '22 12:11 ElPaisano

Noticed a few other errors that aren't in this PR scope but are in CONTRIBUTING.md. Might be good to fix these here.

Line 79: "There're". This should be "There are" Line 27: "Aquire". This should be "Acquire"

ElPaisano avatar Nov 15 '22 12:11 ElPaisano

Line 79: "There're". This should be "There are"

Fixed this because it's weird. I do want it to be known though, that this is technically a grammatically correct contraction.

TMoMoreau avatar Nov 16 '22 18:11 TMoMoreau

Glanced over it, looks solid to me 👍

ElPaisano avatar Nov 21 '22 21:11 ElPaisano

  • Image optimization came back clean!
  • Vuepress build was successful!

filecorgi avatar Dec 05 '22 19:12 filecorgi

Looks like I need @DannyS03 to approve as well to get the "changes requested" thing green.

TMoMoreau avatar Dec 05 '22 19:12 TMoMoreau