This should be a monorepo for all 18F guides

[rogeruiz]

🤔 I have thoughts on better cleaning up our guides. Hunting around Google for all of our different guides which may or may not be in this repo's config file is really daunting and tiring.

Can we discuss in this issue how we can better tackle this. I vote for monorepo with all the guide repos in here. That way we can track changes in one place.

Thoughts welcome highly encouraged ❤️

[cmc333333]

I'd prefer the monorepo, too, at least as a default. If we really want a guide to have different permissions/organization, it can live in a separate repo and be hosted separately. There's nothing stopping us from linking elsewhere.

[wslack]

From another issue:

I am 👎 on this...it's nice to keep the issues for each guide separate, since each is worked on by very different groups of people.

I would separate the question of content management / organization of our guides from putting them in one repo.

One repo is negative for using Federalist, since the entire set of guides would have to be rebuilt with every push to fix a single typo.

[rogeruiz]

hmm, right. Federalist just grabs the current git repository and builds the site with that info. There's currently no way to filter it down to only consume one directory?

Having separate issues.

I generally agree with this, but from my current experience of trying to find a place to reference materials for install Ruby the 18F-way brought me to three separate repos. Having separate issues for each guide makes sense if each guide lived individually on its own, but it doesn't.

For instance, the front-end guide tells users to install a Ruby gem. Where would the troubleshooting, or the guidance for installing the Ruby gem go? Currently it just mentions how to install it. It's not a front-end requirement to know how to install Ruby, but our current workflows and guidance sort of put that stress on front-end engineers and designers.

Without clear troubleshooting or pointing to another guide, it puts a burden on the maintainers of the guide or knowledgable people to help out when consumers of the guide run into any kind of issue. We have a lot of great people who are willing to help and contribute when someone needs help, but when to comes to capturing that knowledge somewhere it can be difficult and then the drive to capture that knowledge is gone. At best, it takes a backseat to other billable work or projects.

We now have two guides that reference developer environments and/or developer standards which I feel is a problem that is caused by siloing our guides into different repositories.

• https://github.com/18F/dev-environment
• https://github.com/18F/development-guide

As a new person at 18F, how do I know which one is where content about troubleshooting a Ruby issue should live?

• I could go by the previous commits to see if the repo is stale.
• I could open an issue in one of both of them and see if it gets any traction. But who would I @mention?
• I could write up the documentation and open a PR with my changes to one of both of the guides. But who would review it and merge it in?
• I could bring it up in Slack? But which #channel? What if there is an ongoing conversation or if it goes ignored?

These choices are just a few of the things that could happen when multiple guides are as separated as they are now. We don't seem to have a shared language around how we name our guides. For instance, the guides don't all follow a naming convention.

• https://github.com/18F/rugged-devops
• https://github.com/18F/frontend
• https://github.com/18F/before-you-ship
• https://github.com/18F/accessibility
• https://github.com/18F/agile

Now, we could rename them. Which feels like the better direction here because of the Federalist issue.

I'm not raising this to force any one thing but rather to bubble up real concerns I have for the ability to search through our current guides and to help mitigate some of the concerns I experience when I go looking for guidance on a particular topic or want to create documentation.

Having a shared guide repo would help remove duplicate content. It would also help create a sense of shared collective knowledge around things. This would allow for more collaboration between disciplines between chapters and within chapters. But the Federalist issue seems like it would squash that.

Having a list of guides to maintain, like the _config.yml file here, is yet another thing do when wanting to release a guide. But, I'm generally okay with this as long as we make it easy to grok that we are missing guides from the _config.yml. Without a shared naming convention, it makes it very difficult to test whether or not this file is out of date.

[meiqimichelle]

To put all of this in context, we have a fairly large content (and brand) management problem (not just the guides) across everything 18F produces that will take a significant amount of time and energy to fix, and then maintain into the future. With the current focus on :4300:, I'm not sure it is worth the energy to reorganize in bits and pieces now, or make significant changes, without anyone available to lead the effort :(

I 100% agree that this is a big, hairy, annoying problem that I would <3 to squash to bits, but I'm not sure now is the time. In related news, plz remind everyone within earshot that we need to hire more content designers ;) This is exactly the sort of information architecture and content usability work they're experts in.

[ccostino]

@meiqimichelle you hit the nail right on the head with their being a content and brand management problem in general. In #wg-documentation, @emileighoutlaw, @brittag, and I have been facilitating a long-running discussion about this and for a time there was an effort to put a content inventory and audit under way (@coreycaitlin was spearheading this!). Sadly, there is just not enough time and resources, as you mentioned.

@rogeruiz, the concerns you bring up are definitely a problem with the content and organization of the current guides, infrastructure issues and concerns not with-standing. I'd love if we can get some organization and cohesiveness around the existing dev guides, for instance, and perhaps this is something that can tie into the efforts of @cmc333333, @msecret, and @LinuxBozo as they continue working toward bringing best practices and sensible baselines to our work. I'm sure other chapters would appreciate similar efforts for their areas of expertise as well. :-)

The infrastructure concerns around this largely revolve around trying to preserve the existing URLs we have for the guides since they already are publicly accessible, as well as the ownership aspect of them. And if someone ends up making a mistake building one guide, putting them all together has the potential to bring them all down at once due to something like a syntax or formatting error. More details are discussed in the issue that @wslack mentioned as we had tried to get around this problem via a small router that could sit in front of the guides hosted in Federalist. In reviewing the situation from an Infrastructure perspective, @NoahKunin has also suggested putting all the guides together in one repo as well. To summarize some of the discussion over there, I think this is the easier thing to do and would require less overall effort in the long run.

Lastly, I have heard some talk about shifting guides and content into the new 18F site that has been recently launched. I'm not sure where that stands but from a content management and branding perspective, that feels absolutely right to me. @gboone, can you speak to this at all and if so, what do you and the 18F site team think?

Tying this all together, this does seem to be the right place to have an open issue and discussion around what to do with the guides moving forward since this is the main guides repo. And as mentioned earlier, #wg-documentation is the place to go in Slack to chat more since the working group has been the steward of them! 😃

[gboone]

Reiterating what I said in Slack so it's all in the same place. We're planning on augmenting the guides with new content on 18f.gsa.gov. At this time, there aren't any plans to fully replace any guides or assume ownership of them. There are some cases where we point users to a Guide on the site where we should have content that more specifically addresses the user need. The IAA guide is the best example I can think of off the top of my head. We are not planning on replacing the guide, but we are planning on giving agency reps more information about working with 18F before asking them to read the entire thing. Does that all make sense?

[ccostino]

Thank you, @gboone! Yes, and I appreciate you reiterating what you had said in Slack here. :-)

[afeld]

We decided not to go in this direction, at least for now.