IA: Guides structure and audiences

[coreycaitlin]

In looking at all the guides, they seem to fall into a few categories based on audience and level of information. Here's a rough sketch of possible groupings, just for the ones currently in the nav:

• Working with us (for partners, but good for all 18F to read):
  • Partnership Playbook
  • Agile Playbook
  • Inter-Agency Agreements
• Our best practices (for 18F reference, and potentially shared with peer practitioners):
  • Accessibility guide
  • Content guide
  • Design methods
  • Lean product design
• Ways of working at 18F (18F-specific practices, patterns, processes; may be useful patterns for other to follow)
  • Testing cookbook
  • Automated testing playbook
  • Before you ship
  • Frontend guides
  • Grouplet playbook
  • Guides template
  • Joining 18F
  • Open source style guide

Some that I haven't figured out yet include:

• Dev environment guide
• Federalist content guide
• API standards

Per #27, there may also be value to creating a smaller collection of dev guides within the "ways of working" subset.

See also:

• Naming notes from @mbland here (https://github.com/18F/wg-documentation/issues/4)
• Guides content audit

[mbland]

Without picking on some of the details, I think something in this direction makes a lot of sense. Perhaps we should link up with Content and UX guild folks to do a design studio or something? This might also help knock out #32.

Speaking of which... Oh hai @emileighoutlaw and @brethauer. :wink:

[jessieay]

I like these groups!

There is some fuzziness between "our best practices" and "ways of working at 18F" since I would assume that we would always be using our own best practices.

For example, I could consider https://github.com/18F/frontend and https://github.com/18F/development-guide to be mostly aimed at an internal audience. This is our way of establishing our own preferred best practices for frontend and general development. These are 18F specific. They may be useful to others, but the primary goal for their existence is to reach internal consensus.

Whereas https://github.com/18F/dev-environment and https://github.com/18F/dev-environment-standardization are for external audiences (see related convos on those repos https://github.com/18F/dev-environment-standardization/issues/1 https://github.com/18F/dev-environment/issues/29)

Separating these "aimed at outside" repos from the "aimed at inside" repos, as you indicated above, would be very helpful. I am not sure about the 3rd "best practices" category.

[coreycaitlin]

Completely agree, @jessieay.

For that third category, here's what I was aiming for: it seems like some of our "ways of working" guides are more explicitly written as patterns or examples for other agencies/orgs. This may not be a particularly useful distinction to carry forward — it's more a slight tone difference in the existing guides that I was trying to figure out how to record.

Maybe the right way to handle this is with good intro pages that set up context and establish expectations, so users understand the intended audience and specificity of a guide before they get too far into it.

[jessieay]

It may be worth having a standard intro that is different for each type. Eg: the thoughtbot playbook starts with this:

You work at thoughtbot. This is your playbook. It details how you and your teammates run our software consulting company and how we make web and mobile products together.

http://playbook.thoughtbot.com/

We could do something similar for 18F folks vs other government agency folks

[coreycaitlin]

<3 I like that. I'd definitely want to write through it for each guide to see if it works for all of them, or whether we want to take a slightly different tone for internal/external guides, but this is a great starting-point.