Merge with development-guide ?

[jessieay]

Hi there! I just found this guide via the Hub. I was about to create a page in https://github.com/18f/development-guide to address some of these same issues.

What do people think about merging this repo with https://github.com/18f/development-guide?

I think that "dev environment" sounds like a nice sub-topic of "development" generally. And I think having the guides in one place would make it easier for people to follow the discussions and improve overall guides awareness.

[afeld]

I didn't write either of them, but makes sense to me.

[jessieay]

thoughts, @mbland @emileighoutlaw @johnscancella (you three are top contributors to this repo according to github)

[johnscancella]

I'm torn to be honest. One the one hand they are related in that they both focus on development and there is some overlap. On the other hand the content in that development-guide to me feels to be more along the lines of a particular development style which doesn't match the more generic dev-environment guide. Just my $0.02, I will happily go along with the majority.

[mbland]

I'm with @johnscancella. I'd like to keep them separate, in much the same way the Testing Grouplet has the higher-level https://pages.18f.gov/automated-testing-playbook/ (which seems analogous to this guide) and the more detailed https://pages.18f.gov/testing-cookbook/ (which seems analogous to the development-guide).

[jessieay]

@johnscancella @mbland can you explain in more detail why dev-environment and testing-cookbook are different in scope from development-guide?

My feeling is that having them all together would get them in front of more people. This would be a win because more people would actually read them and use all of the great resources they contain. When they are split up as they are right now, they aren't referenced very often. Anecdotally, I mentioned dev-environment to a few developers this morning and none even knew it existed.

[mbland]

No, I think we've given enough detail. We're preparing to announce the dev-environment guide in a blog post soon.

[kaitlin]

I'm with @jessieay. When onboarding some of the new folks it's been difficult to track down and present this content in a coherent way. Also, are we going to just keep adding guides to https://pages.18f.gov/guides/ forever? I feel like if we do that it will just become a big 'ole IA mess. I think it makes sense to be a little more thoughtful here w/r/t the presentation. It would be great to group similar or closely related guides under an umbrella guide.

IMO, this slots nicely as a subtopic in an overall "Developing at 18F" guide. One part is about your environment, one part is about code reviews, one part about testing, etc.

Looping in @melodykramer and @andrewmaier as they can probably offer valuable input based on their experience re-architecting the info in the hub.

[mbland]

I'm all for creating a better IA for the guides, and aim to set @melodykramer, @andrewmaier and others upon that task. And I'm all for creating umbrella guides that fork off to sub-guides, a la "Developing at 18F". I'm just convinced that this guide should remain distinct from the other one.

[kaitlin]

But why? Isn't it part of the process of developing at 18F?

[mbland]

Because I don't think lumping everything that could conceivably be lumped together in a single document is the solution, either. And I think that in this case, broadly outlining what a sane dev/devops environment looks like in an encapsulated document serves a purpose very different from telling people about how to do code reviews and use git. An umbrella guide would be far more suitable for linking them together.

[kaitlin]

I'm not suggesting lumping everything possible together in one document. I am saying that all of these guides seem very closely related and could benefit from being more tightly integrated and being presented to their audience in a more cohesive fashion.

I'd also ask, who is the intended audience? If the the intended audience is developers at 18F or on other dev teams in the government, I think it makes sense to update the presentation to incorporate feedback you're actively getting from that audience.

I think the benefits from combining these guides are:

• Everything you need to know about best practices w/r/t to developing at 18F are in one place
• Easy to find/notice new subsections as they're added
• People don't miss other critical pieces because they didn't scan the entire guides list closely

What are the benefits of keeping them separate? I think that is a valid question.

[mbland]

I'm agreeing to an organization that combines all the different guides under an umbrella, or a series of umbrellas. I'm not agreeing to lumping this guide in with the other one for the reasons I've already articulated. By that same logic, we should lump testing, accessibility, APIs, Frontend, and the Authentication guide I'm drafting all into a single mega-repository. I will not agree to do that, as I don't think it serves either the readers or the content creators to mash them all together at that level.

By all means, start an umbrella guide for "Developing at 18F", and we can begin having a discussion around what the top-level items in that guide should be, and even move the home page links from the main /guides page underneath that new umbrella. But I will not agree to merge this guide or any of the other existing guides directly into another one.

[mbland]

Filed 18F/guides#27 to continue the discussion there.

[mbland]

BTW, just want to offer apologies for being kinda ornery here... My fault for being a bit rushed and impatient in my responses. That wasn't cool.

[jessieay]

I'm agreeing to an organization that combines all the different guides under an umbrella, or a series of umbrellas. I'm not agreeing to lumping this guide in with the other one

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)

[jessieay]

via 18F/guides#27 (comment)

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.

@johnscancella thanks for the background; I wasn't clear that the intended audience of this repo is not developers. As @kaitlin suggested, I will add developer-specific dev-environment information / guide to the development-guide repo as a sub-section.

The confusion seems to be partially a documentation thing (can we updated the README of this repo to explain its purpose?) and partially a naming thing: I would assume that any "guide" would be practical set of suggested best practices to follow. I would expect a higher-level document, like this one (?), would be a "playbook".

Related: 18F/wg-documentation#4

There is nothing in there about playbooks, but it does seem like a separate category.

[johnscancella]

@jessieay I didn't realize there was a such a thing as playbooks, I apologize. Since that is the case I would propose it gets renamed to be dev-environment playbook, or something along those lines.