[CORE-859] New Docs

[MoonMoon1919]

This PR is an amalgamation of many PRs that include work to revamp the IA (Information Architecture) of the docs site as well as writing all of the new content for that new IA.

[netlify]

✅ Deploy Preview for pensive-meitner-faaeee ready!

Name	Link
🔨 Latest commit	db4b9b5
🔍 Latest deploy log	https://app.netlify.com/sites/pensive-meitner-faaeee/deploys/647612deb13b310008ff0ee5
😎 Deploy Preview	https://deploy-preview-772--pensive-meitner-faaeee.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[ebeneliason]

Thanks for this! If I'm not mistaken, this includes proposed IA for most new docs sections now, not just IaC. Is that correct? I barely had a chance to peek at this, butI I intend to give it full attention tomorrow. I propose to share the next round of feedback async, at least to start. Would adding thoughts as comments here in this PR be a good place to capture them, or would you prefer a different approach? (Notion pages? Directly in Jira?) Let me know your preference(s)…

[MoonMoon1919]

this includes proposed IA for most new docs sections now, not just IaC. Is that correct?

That's correct! I've updated the PR message accordingly.

I propose to share the next round of feedback async, at least to start.

Agreed!

Would adding thoughts as comments here in this PR be a good place to capture them

I think here would probably be easiest, so we can iterate relatively quickly and see what it looks like on the PR app.

@ebeneliason ^

[ebeneliason]

Meta comments

This process for previewing the IA is extremely helpful. Thanks for taking the initiative!

There's a lot of feedback below. Don't take it as gospel, and don't let it detract from all the excellent work here so far. I'm really excited about how things are shaping up. Use it as you find it helpful, keeping in mind I lack both context from your prior conversations and a deep technical understanding so it won't all be right. Give it a read, think it over, and let's plan to meet soon to get in sync.

I think we might be overusing the card listing pages a bit. There are three main navigational options at hand: 1) header nav 2) sidebar nav and 3) in-page card nav. I suppose there's a fourth option if you distinguish top level and submenu dropdown in the main nav area. We made heavy use of card nav in the past partly because we had these gargantuan guides that themselves contained many subsections, and were intended to read from start to finish. We often used cards as a way to link to new guide sections with their own dedicated sidebars, which would have felt less natural to do from a sidebar nav item.

In the current proposal, we're creating separate sidebars for each product area. Is that the right approach? It might be, but I've been pondering the benefits of having the efficient browse-ability of a full sidebar for all product docs. Even if we do split them out per product, I prefer the immediacy of the dropdown navigation from the first iteration to the new card index. I propose that the new card index you've constructed here would make a better replacement for some of the content on the home page of the docs.

As a last general note, let's try to be consistent with language in our section headers. In a few places we have "What is all this?" sections. I appreciate the less formal tone, but it lands slightly too far on that side for me. I'd prefer we standardize on something innocuous like "Introduction" or "Overview." I also prefer "Getting started" a bit to "Learning". There might be others. That's not to say we have to stringently adhere to the same conventions everywhere; but if we use different terms for similar concepts, we should do so with specific intention.

Patcher

I've pushed this story down into the backlog (and may just delete it). While I agree it definitely belongs top level in the docs, I think the responsibility for those docs should fall to the Patcher team. Since Patcher is in private beta, they may not want the docs exposed publicly yet.

Developer Portal

I know a new story was created to cover this section, but I want to push back and suggest that if we do break it out from the intro, we need to cover the corresponding IA work for the new section with the same story. Otherwise we put ourselves in a position where we might lose access to docs that folks depend on to gain access to our code.

I'm coming around to calling it "Developer Portal", as long as internally we understand that the content belonging there is purely administrative, and that any product features within the portal should live in their corresponding sections. The IA shown here may be sufficient for our immediate needs, although:

1. We might consider rephrasing/renaming some of the content to read less like a step-by-step in this new context, e.g. "Managing My team" and "Signing In" etc.
2. Coming at it from an administrative angle, we could also include information on things like billing, subscription details, etc.

IaC Library

• What's the right title here — how much discussion went into the currently proposed one? We should try to standardize on our messaging to avoid confusion about what it is when we reference it across docs and our marketing site.
• Upon further reflection, I really do believe we should keep the "Library API Reference" separate from the "IaC Library Docs." There are a few reasons for this:
  • We've heard from customers that they'd prefer a stronger distinction between learning and reference materials
  • Most similar platforms keep API docs separate from learning docs and guides (e.g. Stripe, Terraform, etc.)
  • Regular users will need API docs the most — they shouldn't be buried several clicks deep
  • Our goal is to continue expanding on the module and service reference in a manner consistent with what could eventually be extracted into its own first-class library (akin to the Terraform registry), so keeping a clean semantic break between that and the rest of the "meta" library docs seems appropriate.
• I'm not opposed to breaking out "modules" and "services" in the intro — in fact, some earlier IA sketches I made did the same — but I also wonder whether it might be more useful to have a single "Modules vs. Services" page where we contrast them in order to explain their similarities and differences.
• I still find "Usage" to be highly general, but I can come around. For consideration, might we break this into e.g. "Working with modules" and "Staying up to date"?
• Is "Support" the right title for the last section? I'm almost tempted to make "Contributing" the header, but then I'm not sure how to distinguish the page itself. Maybe "Feedback"? I might be overthinking it — "Support" could be fine.

Reference Architecture

• What's the distinction between "What is all this" and "What is a Reference Architecture"? Maybe we only need one?
• I suggest adding an "Understanding the deployment process" or similar page within the "Overview." This would differ from the "What is it" pages above, which would describe the thing itself, and instead focus on an overview of the steps that one goes through from purchase to production.
• Boostrapping
  • "Bootstrapping your Reference Architecture" -> "Configuration"?
  • Path 1 and 2 — I don't think we need a separate page for path 2. I think we should present our preferred approach, and we could have a mention or even a callout on that page which suggests to contact us if you prefer to do it without our CLI tool.
  • Without seeing the content it's hard to know, but I wonder whether it might be worth introducing the CLI tool at a high level on the page in the outline, but then also having separate pages which enumerate the steps that it will walk you through, so it's clear what's actually happening. Creating accounts, setting quotas, whatever. Each of those steps could use explanation, and I think it would be more obvious to the user what's happening if those were enumerated instead of just having a page about a tool that's totally unknown to them.
  • Should we include a page all about pre-flight checks here? Explain what they are, how to trigger them, what to expect (and to do) when hitting errors, etc?
• The "Usage" section feels weak.
  • The support link here probably disappears given the support section below.
  • We might consider breaking out the sections for adding accounts, undeploying modules, etc. so that the "things you can do" are visible in the sidebar, even if the pages are short and sweet.
  • Shouldn't there be a section for "adding" or "extending" or something, to suggest that it can be augmented? Even if this just links to the IaC library for the meat, I think it's useful to reinforce that doing so is an expected/allowed action.
  • Pipeline reads a little like a step by step. Is it? Is that the right form factor here?
• Access
  • Should this come before the usage section?
  • The "Do this first" callout feels off. If this is a do it first item, why is it so far down the sidebar. Or perhaps we could just call this something like "Configuring AWS Authentication" or even just "Setting Up AWS Auth"
  • I recommend phasing the sections to highlight their differences instead of their commonalities, e.g. "VPN Authentication", "AWS Console Authentication", "CLI (command line) authentication", etc.
• Support
  • At first I wasn't sure what might go here. But then I realized it might be worthwhile to plug, in yet another place, the onboarding call we offer every new subscriber. What else? Anything unique to RefArch? We do have the header nav support link, too, so lets make sure any additional support sections are holding their weight.

Pipelines

• In some of the other products we have "Getting Started" sections. It might be nice to use that instead of "Learning…", for consistency.
• I realize it's probably just a basic tutorial, but even so it might be nice to incorporate the content in the title somehow, e.g. "A Basic Pipelines Tutorial", "Single Account Pipeline Tutorial" or "Hello, Pipeline"?
• We should use the auto-expanded sections here like the other products, again for consistency.
• "Deploying Multi-Account Pipelines" — we discussed possibly moving this out of learning, but I can't recall. Not arguing one way or the other, just checking to see if keeping it here was intentional.
• I have the least understanding of the details of this product area, so I defer mostly to you on the rest of the content!

Landing Zone

• What's the plan/timeline for this section? Are there obvious things we should document right away even if a complete effort comes later? Or are we leaving this out for now?

[ebeneliason]

Oh, a couple more questions for RefArch:

• Should we include a page on setting up SSO?
• A page with an overview of the overall folder structure and patterns employed? (including envcommon, or even break that out?)
• What about the prerequisites?

[MoonMoon1919]

Just putting some responses here. We can plan to sync live soon!

What's the right title here — how much discussion went into the currently proposed one? We should try to standardize on our messaging to avoid confusion about what it is when we reference it across docs and our marketing site.

The marketing site refers to it as Infrastructure as Code Library in the drop down, so that's what we went with here. I'm hesitant to refer to it is IaC in the drop down because we won't have the opportunity to spell out the shorthand first. Everywhere else I'm fine referring to it as IaC, as long as we explicitly spell it out first (e.g., Infrastructure as Code (IaC).

Upon further reflection, I really do believe we should keep the "Library API Reference" separate from the "IaC Library

Updated - it's back in the top bar now.

I'm not opposed to breaking out "modules" and "services" in the intro — in fact, some earlier IA sketches I made did the same — but I also wonder whether it might be more useful to have a single "Modules vs. Services" page where we contrast them in order to explain their similarities and differences.

As a user/frequent consumer of docs (in general) I tend to prefer modules and services be split out.

Thinking from the "what questions would the user be asking" perspective, what if we renamed them What is a module? and What is a service? Each page already contains a "when to use a <module|service>" section, so should we let that information speak to the "vs" concept and let the users draw their own conclusion?

I still find "Usage" to be highly general, but I can come around. For consideration, might we break this into e.g. "Working with modules" and "Staying up to date"?

Updated - I think maybe Working with the library instead of Working with modules since modules is an overloaded term.

Is "Support" the right title for the last section? I'm almost tempted to make "Contributing" the header, but then I'm not sure how to distinguish the page itself. Maybe "Feedback"? I might be overthinking it — "Support" could be fine.

I think Support is good. Submitting issues and contributing both fall loosely under that umbrella.

[eak12913]

LGTM

[pete0emerson]

🚢