search

googlefonts / googlefonts.github.io

Google Fonts documentation
https://googlefonts.github.io
Apache License 2.0
58 stars 27 forks source link

The upstream.html page should explain the "Use this template" workflow explicitly for clarity #123

Closed n8willis closed 3 weeks ago

n8willis commented 11 months ago

Related to #122. The upstream.html page does not say how to create a new repo based on the project-template. The "The Google Fonts Project Template repo" section lists its background and some of the benefits, but it doesn't say what to do, and the next section "The essentials explained" discusses things that aren't related to set-up.

Technically, the one-minute vid by Simon does say to click on the "Use this template" button, but that's not an ideal way to relay that information. (1) it's an off-site reference, (2) it's Twitter, which not everybody has (and maybe requires sign-on to see? I can't keep up with how that's changing week-to-week), (3) it's video not text, (4) it's deliberately going as fast as possible, and (5) it's very small and not easily readable what is being shown in the screenshots.

Here again, I think I have encountered type designers new to GitHub who have been tripped up initially by this step, and although I can't say for certain that they read this page, it's certainly possible and, if they did, I think it's likely that they didn't take away the correct sequence of steps they'd need to start a new project repo from the template.

If the intended workflow is that new designers should use the "Use this template" button on the project-template repo, this page could say that explicitly and readers would be less likely to make a misstep at the beginning.

Secondarily, the info about a minimalist repo structure that is found in the "The essentials explained" section seems orthogonal enough to be a separate document, for reference by people who are not attempting to follow the suggested workflow, or at least moved to later. It seems like re-titling the section could also help make it clear that it is not a sequential step after the "The Google Fonts Project Template repo" section. Maybe "Manually-built repository structure requirements" or something like that, depending on what the main intent is?

vv-monsalve commented 3 weeks ago

@n8willis This issue was probably filed before the instructions were in writing, but the instructions on how to use the template are now included in the Template Readme. Users will need to read them there.