Closed
Description
What article on docs.github.com is affected?
The specific README.md
files for both variables and reusables; CONTRIBUTING.md
What part(s) of the article would you like to see updated?
As they are now, these files are a little bit dry - it's not something that's intuitively usable by first-time contributors. I suggest both of these files could be updated to look like the one for liquid tabs, with references, usage examples, etc.
Also - adding a brief section on each of these (liquid tabs, variables, reusables, etc) would be extremely helpful.
Content design plan
- Open for an OS contributor: For specific
README.md
files, I think they should be as complete as possible: definitions, examples, everything that a content contributor could learn about what's being referenced (code intrincacies = negative scope). - @janiceilene will make these changes: As for
CONTRIBUTING.md
: IMHO it should be a complete quick start. Let's take, for instance, the last 24h: I was learning about variables, reusables, and callout tags as the PRs were reviewed. I mean, the technical detailes are there if I follow the md links, but the text doesn't give me any reasons to do so. And even if I do it, there's no clear benefit for the newcoming contributor - it reads and feels like technical documentation (which is technically not wrong, but not necessarily helpful to a newcomer as such).- Structure the CONTRIBUTING.md file more like a quick start guide - "welcome, here's the basic stuff you need to know, here's why you need to know it, here's where you can learn more about each of them" - paced, with simple examples. Perhaps something like this.