Skip to content

Improve documentation on variables and reusables #210

Closed
@casals

Description

@casals

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    contributing docsContent related to our contributing docshelp wantedAnyone is welcome to open a pull request to fix this issue

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions