Apply information architecture to the Guides

[mbland]

As evidenced in 18F/dev-environment#29, the time has now come to seriously set about applying some information architecture discipline to the https://pages.18f.gov/guides/ home page.

First and foremost, it seems there's a pressing need for a "Developing at 18F" guide to surface a number of dev-specific guides, such as the current development-guide, dev-environment, the testing guides, accessibility, and others. I'm opposed to merging the dev-environment guide into the development-guide specifically, but I am in favor of an "umbrella" guide. (Or perhaps the development-guide could itself become that umbrella?)

So the question is, can we hash out an architecture that makes sense purely via this issue, or shall we convene a meeting to do some brainstorming/research on how to better organize what we've got?

Thoughts?

cc: @jessieay, @kaitlin, and @afeld from 18F/dev-environment#29

cc: @andrewmaier @melodykramer @emileighoutlaw @kategarklavs @awfrancisco because this is your bread and butter

[melodykramer]

I agree that this needs a look but think we should wait until we've hashed out @mtorres253's Problem Statement. I don't want to jump into something here, and then realize we need something different based on the needs that come out of that effort. (i.e. we can fold this into that effort.)

[mtorres253]

I agree as with @melodykramer Let's see how this maps to the problem and prioritize from there. I'll update the doc based on this convo.

[jessieay]

Hi @mbland - thank you for opening this issue.

As I mentioned here,

I think the development-guide itself could serve as as good home or "umbrella" for topics like https://github.com/18F/dev-environment, https://github.com/18F/code-style-guide, https://github.com/18F/testing-cookbook, and and other development-type guides.

It seems like you might have a different idea about what it means to merge repos vs. this "umbrella" concept.

What I was imagining was that we could create a sub-directory within https://github.com/18F/development-guide/tree/18f-pages/pages called "dev-environment" that would have the same pages as https://github.com/18F/dev-environment/tree/18f-pages/pages has now (which would mean we'd no longer need the separate dev-environment repository)

I am not sure what that subdirectory plan would look like at https://pages.18f.gov/guides/, but I am not sure the rendered markdown at the page matters as much as the content being discoverable and editable within GitHub. As far as I am concerned, the dev guides could just be a set of organized markdown files

My reasoning for this is as follows:

1. the audience is developers and they are comfortable reading stuff on GitHub
2. the main way developers will be interacting with these guides, aside from referencing them (see "1"), is making changes via GitHub PRs in order to have conversations about the way we work here at 18F

I think Melody and Michael are right that this should be part of the larger problem statement.

My long-term suggestion is not to improve the architecture of the guides but to just let our dev guides just be simple markdown in a single repository.

My short-term suggestion is to put the content of https://github.com/18F/dev-environment into https://github.com/18F/development-guide per the convo in 18F/dev-environment#29 (we can go back to discussing that particular issue on that particular GH issue)

[johnscancella]

the audience is developers and they are comfortable reading stuff on GitHub

Not to add more confusion to the mix, but most of the information (if not all) in https://github.com/18F/dev-environment is aimed not at the developer but more for upper management/IT management. Or at least that was my intent when doing pull requests.

If we do merge https://github.com/18F/dev-environment into https://github.com/18F/development-guide I would like to suggest we create an area that is less technically detailed that we can point management to so that they understand from a high level why we need certain equipment/money/manpower/etc.

[kaitlin]

Ahhh @johnscancella that makes more sense now. 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).

@jessieay in this case it sounds like these really are two different things. Why don't you put your 18F specific dev environment info into https://github.com/18f/development-guide as a subsection? That way we still have the one guide to point 18F devs to.