Consumer guide, versus Contributor guide

I’ve written before about how typefaces stored on GitHub (public or private) would be better off with a README, but it’s easy to think that just because something is on GitHub, the information that should go in the main text documentation file should go deep into the technical details.

I don’t think this is always true.

GitHub, building on existing conventions, lets you distinguishes a README file (README.md, README.txt, etc.) from the Contributing guidelines.

For type design projects, here’s one way to think about it: the README file is effectively the main instructions that come along with the download package containing your font.

It might include installation instructions, some of which might get into technical details, but ultimately you probably aren’t going to mention your font editor—except to say “see the contributing guide.”

The contributing guide is what you’d want your colleague to know (or you in the future), if they needed to keep working on the project.

Once you’re on GitHub, it’s easy to put all technical details in the README, and certainly doing that is better than not writing any documentation at all. At some point, through, separating who you are writing to—someone looking to “consume” your fonts in their own software or project, or someone looking to “contribute” to the fonts themselves—lets you provide a shorter, more relevant guide to both.

Until next time,
Kenneth