Open nelsonic opened 7 years ago
I think that whether we put it in https://github.com/dwyl/learn-html5 or https://github.com/dwyl/learn-markdown, we can't really realistically expect that people will go through the whole tutorial if they think they already know those things, particularly if they are new to dwyl. It should certainly be in one of those anyway.
I would suggest that what we actually need is a checklist of things that reviewers will be looking out for (that checklist can link to the more content heavy learn-x repos) that we then add as a message to a PR template for all our repos.
@iteles a checklist for content reviewers is a really good idea! 😍
The reason we can expect
people to go through the "whole tutorial" is because we are going to design the learning UX that way ... 😉 (as discussed in the park ages ago #LearningOrganisation ...)
@dwyl we really appreciate getting contributions from the community. ❤️ ✅
But we often get contributions that end up requiring more work to "fix" than necessary...
This is not the fault of the person making the contribution, rather it's the my fault for not setting appropriate expectations i.e. communication fail. 😞
Not to "pick" on anyone in particular ...
this
happens from-time-to-time but I tend to "correct" it with PR comments instead of fixing it "systematically" with better instructions!The Issue
Links to content where the link text does not give the reader any clue what the content is.
The Downside(s) of Non-Semantic Link Text
There are several disadvantages to having non-semantic link text, here are the "Top 5 Reasons non-Semantic Link Text are Bad":
Why Not Simply Use (Paste) the Full URL?
I prefer to simply paste the entire link in the body of the Markdown text especially when the URL is reasonably semantic / human readable.
For example:
If this person had simply written "Screaming Architecture" I would probably not have clicked on it.
But the fact that the article was written by "Uncle Bob" (who I briefly met @GRPN and highly respect!) immediately got my attention.
TODO
[ ] Decide where we should put the instructions (@iteles thoughts?)
[ ] Write clear beginner friendly instructions for people on how to create great links in:
should
we be writing "Raw" HTML[ ] Link to Authoritative/Relevant "Background Reading" e.g: