Skip to content

Improve documentation on variables and reusables #210

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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