Naming convention for GH repos related to 18F standards

[jessieay]

This is a sub-thread of #3

Here is a semi-comprehensive list of GitHub repos/directories for things that tell people how we at 18F like to do things:

https://github.com/18F/testing-cookbook
https://github.com/18F/frontend/tree/18f-pages-staging/pages/css-styleguide
https://github.com/18F/open-source-guide
https://github.com/18F/content-guide
https://github.com/18f/engineering-best-practices
https://github.com/18F/hub/tree/master/_pages/standards

Keywords used are:

• standards
• best practices
• guide
• cookbook

The most commonly used word is "guide" - I think this would be a good term to standardize on for this type of GitHub repo and/or page because it does not sound as hard and fast as "standard" and I feel like "best practices" is saying that we know what's best, when a lot of time guides are just agreed upon norms (with people recognizing that there is no one best way to do anything).

So, if that is what we standardize on, we could rename repos to:

https://github.com/18F/testing-guide
https://github.com/18F/frontend/tree/18f-pages-staging/pages/css-guide
https://github.com/18F/open-source-guide
https://github.com/18F/content-guide
https://github.com/18f/engineering-guide

(leaving the hub standards out since I know there are people working on re-architecting all of the Hub content already)

What do others think of this change? I think we could also call any of these a cookbook or standard or style guide but so far my vote is for guide

[jessieay]

Related GItHub PR: 18F/guides#24

[jessieay]

via 18F/guides#27 (comment)

Maybe when we do the larger IA work here we can pick out the guides that are more playbook-y (like open source, agile, etc) and collect them together in an umbrella guide for leadership/management (I do think there could be a better name for the guide that is less confusing but maybe that's just me).

I would suggest "playbook" for a higher-level type guide that is aimed at leadership/management. eg: https://playbook.cio.gov/

[mbland]

Yeah, having an established convention around "guide", "playbook", and "cookbook" even would be helpful. Just spitballing to get ideas flowing in advance of proper research:

• "playbook": the high-level justifications/strategies that benefit managers, as mentioned above, that can apply to any organization
• "guide": more deeply technical explanations of fundamental concepts, but not very specific to tools, languages, platforms
• "cookbook": very specific technical info based on specific languages, tools, etc. (e.g. https://pages.18f.gov/testing-cookbook/)
• "handbook": a guide for a specific process or organization