Gruntwork Production Framework

[brikis98]

This PR adds the Gruntwork Production Framework write-up to our docs site.

Direct link: https://deploy-preview-145--pensive-meitner-faaeee.netlify.app/docs/guides/production-framework

• Convert the content in the Notion page to the docs site format.
• Add images.
• Refactor / clean up. Major changes:
  • Merged the "Requirements" ingredient into the very intro section. I wanted to have just 5 ingredients (easier to remember, market, etc), so this content is now a "pre-requisite" for the framework.
  • Merged the Application Catalog content into the Service Catalog. I wanted to have just 5 ingredients, so it made sense to join this with the Service Catalog.
• Figure out how to expose this content on the docs site. Where in the nav should it go?
  • Should this be a new top-level thing in the Intro section? It feels quite long and I'm worried customers trying to get started will get lost in this content.
  • I put it in the Guides section, but as per [APT-1617]? Guides sidebar refactor #132 (comment), I have no idea how to expose it there.

[netlify]

✔️ Deploy Preview for pensive-meitner-faaeee ready!

🔨 Explore the source changes: 14c6ad2

🔍 Inspect the deploy log: https://app.netlify.com/sites/pensive-meitner-faaeee/deploys/61eb05917321800007362a5f

😎 Browse the preview: https://deploy-preview-145--pensive-meitner-faaeee.netlify.app

[eak12913]

Is this outline needed? It's there in the sidebar and the previous paragraph can have links to the intro sections of each major section like "ingredients", "recipes" and "solutions"

[ebeneliason]

I was thinking along the same lines. I'm also wondering about the image shown up front — perhaps that would be better off as an ordered CardList — then it could serve as the outline, and each card could link directly to the corresponding section.

For an example of what I mean, see this intro page. These cards also support icons, so we could get something that functions very similarly to the image shown that doubles as a clickable index.

[brikis98]

For relatively long content, I find it's helpful to see an outline before diving in: like seeing the high level map before doing the turn-by-turn directions.

Most tutorials I've seen do this. The intro page Eben linked to is a perfect example of that.

I don't think the nav on the left quite handles this. For one thing, it is collapsed by default, so you can't actually see the whole outline. But even more importantly, it's on the left, so it's not the normal place to look as you're reading.

I liked the image as a single, shareable thing that would hopefully be used if someone shares this on social media. Breaking it up into the outline would help with the ingredients, but not the rest of the outline (the recipes, how gruntwork can help).

That said, turning the outline into cards might look better. I guess I'd need to see it. That said, it doesn't seem critical, and I'd like to get this merged and deployed; Josh is already using it in sales calls (as in, our preview env version!). Perhaps file a bug and come back to this later?

[ebeneliason]

This is fantastic! I look forward to reading through it in full.

I agree this is probably too much to throw at someone just getting started, but I think the core concepts presented here are foundational to the whole Gruntwork experience, so I'd like something in the Intro that sets the stage for what's to come.
At the risk of asking for yet more content, how would you feel about creating a significantly abridged version as a teaser, of sorts — that touches on the main topics and overall rationale, but doesn't get into the details — to include in the intro? I think it could manifest as a single page with an overview of the key elements, a link to the full guide, and a promise that there will be time to dig into the details later.

We should continue the conversation regarding the guides presentation in the other thread, but in the meantime, perhaps we should find a place to drop a new card that links to this one. Maybe both the Intro > Next Steps and Guides pages serve cards 3-up, as in:

• The Gruntwork Production Framework
• Set Up Your Reference Architecture
• Build Your Own Architecture

[eak12913]

This looks good! We'll start looking things over and providing input. One thing to consider is that this probably doesn't belong under guides and should really be living in the intro area.

[ebeneliason]

This looks good! We'll start looking things over and providing input. One thing to consider is that this probably doesn't belong under guides and should really be living in the intro area.

Given the extensiveness of this guide my perspective has shifted, and I think perhaps it can live on in this format. I suggested above that we consider creating an abridged (e.g. one page) version of this to include in the intro itself to introduce the concepts without enumerating all the details.

[eak12913]

We should consider whether it makes sense to collapse some of these sections into pages with subsections. There's a lot of folder hierarchy here now but the individual sections of each area are pretty short and sweet.

[eak12913]

Given the extensiveness of this guide my perspective has shifted, and I think perhaps it can live on in this format. I suggested above that we consider creating an abridged (e.g. one page) version of this to include in the intro itself to introduce the concepts without enumerating all the details.

This guide feels more like a mini "Modern DevOps Up and Running" book... each area is like the intro section of each chapter

[brikis98]

I agree this is probably too much to throw at someone just getting started, but I think the core concepts presented here are foundational to the whole Gruntwork experience, so I'd like something in the Intro that sets the stage for what's to come. At the risk of asking for yet more content, how would you feel about creating a significantly abridged version as a teaser, of sorts — that touches on the main topics and overall rationale, but doesn't get into the details — to include in the intro? I think it could manifest as a single page with an overview of the key elements, a link to the full guide, and a promise that there will be time to dig into the details later.

I think it's a good idea to mention it in the intro... But I'd prefer to avoid blocking this PR on that change. It'll take some time to think through where to put it in the intro, the right level of detail to go into, and so on, and Josh mentioned he was thinking of making other changes to the intro anyway. So perhaps file a bug and come back to this?

We should continue the conversation regarding the guides presentation in the other thread, but in the meantime, perhaps we should find a place to drop a new card that links to this one. Maybe both the Intro > Next Steps and Guides pages serve cards 3-up, as in:

• The Gruntwork Production Framework
• Set Up Your Reference Architecture
• Build Your Own Architecture

The intro sentence on the guides page says, "As a Gruntwork subscriber, you have two primary ways to engage with our library." That doesn't really work if we add a 3rd card, right?

[brikis98]

This looks good! We'll start looking things over and providing input. One thing to consider is that this probably doesn't belong under guides and should really be living in the intro area.

Given the length, I think guides is probably the right place for this. I imagine most customers going through the intro section are looking for a short path to using the product, not a long, detailed overview guide...

[ebeneliason]

I think it's a good idea to mention it in the intro... But I'd prefer to avoid blocking this PR on that change. … So perhaps file a bug and come back to this?

Agreed 100%. This adds value immediately. I'll file an issue to remind us to add it to the intro later.

The intro sentence on the guides page says, "As a Gruntwork subscriber, you have two primary ways to engage with our library." That doesn't really work if we add a 3rd card, right?

Yeah, we'd have to rephrase. The WIP PR for the guides sidebar updates actually replaces that with a "Fundamentals" section that links to the intro and this new guide, so we can avoid the issue there. That PR is almost ready, I think, so we could wait to release until it lands, maybe even later today.

As for the Next Steps in the Intro section, perhaps we can say something like: "We recommend reading about The Gruntwork Production Framework to get a more complete understanding of how your team can leverage your Gruntwork subscription. After that, there are two primary ways to engage with our library."

(Rephrase this as you like!)

[brikis98]

Agreed 100%. This adds value immediately. I'll file an issue to remind us to add it to the intro later.

Roger, thanks!

Yeah, we'd have to rephrase. The WIP PR for the guides sidebar updates actually replaces that with a "Fundamentals" section that links to the intro and this new guide, so we can avoid the issue there. That PR is almost ready, I think, so we could wait to release until it lands, maybe even later today.

As for the Next Steps in the Intro section, perhaps we can say something like: "We recommend reading about The Gruntwork Production Framework to get a more complete understanding of how your team can leverage your Gruntwork subscription. After that, there are two primary ways to engage with our library."

(Rephrase this as you like!)

OK, what I did is added a new sub-page to the "Core Concepts" menu in the intro section, which uses the same image of the Production Framework, and links to the full guide for the rest: 5565762

Perhaps we can merge this PR with just this entrypoint for now... And then in the PR where you are re-working the Guides landing page/nav, you could include this Production Framework guide as one of the links to create a second entrypoint?

[ebeneliason]

Perhaps we can merge this PR with just this entrypoint for now... And then in the PR where you are re-working the Guides landing page/nav, you could include this Production Framework guide as one of the links to create a second entrypoint?

That works for me. I've already got the card in place awaiting the content to merge.

[brikis98]

Roger.

Could I get a "ship it" on this so I can merge?

@josh-padnick was going to provide feedback, but seems busy. Perhaps we're better off merging what we have here as-is, and we can make further changes in subsequent PRs.

[josh-padnick]

Hey Jim, I've already done an initial review and used this in sales meetings! I just haven't had time to do a comprehensive review yet. I can commit to getting that done by this week.

Side note: This repo is public. I wonder if there are ever any docs we'd rather discuss in private (from the world, not from our own team). For now, I'll plan on commenting here later this week, though likely not till Tue or Thu.

[ebeneliason]

Could I get a "ship it" on this so I can merge?

We'll merge it for you. I was hoping to get this in on Friday, but I wanted to sync with Eugene first since he gave a full review and time (zones) didn't allow it — I expect we'll merge today. It's a great improvement even if there are changes to make after Josh has time to dig in deeper.

[brikis98]

Hey Jim, I've already done an initial review and used this in sales meetings! I just haven't had time to do a comprehensive review yet. I can commit to getting that done by this week.

Roger, thx!

Side note: This repo is public. I wonder if there are ever any docs we'd rather discuss in private (from the world, not from our own team). For now, I'll plan on commenting here later this week, though likely not till Tue or Thu.

I suppose if the docs relate to some sort of internal company details / strategy we don't want to reveal publicly, yea, perhaps.

On a related note, should the docs repo be public? We made the original marketing website public because, IIRC, it was a Jekyll / GitHub Pages site, and that was an easy way to manage/deploy it; and I think we kept it public so we could easily link customers to "diffs" in our ToS. FWIW, neither site is "open source" (the licenses are proprietary), and we don't really want anyone copying the content/styles here.

So perhaps we make the docs site private? And eventually, the marketing website too?

[brikis98]

Could I get a "ship it" on this so I can merge?

We'll merge it for you. I was hoping to get this in on Friday, but I wanted to sync with Eugene first since he gave a full review and time (zones) didn't allow it — I expect we'll merge today. It's a great improvement even if there are changes to make after Josh has time to dig in deeper.

Roger, thanks!

[josh-padnick]

So perhaps we make the docs site private? And eventually, the marketing website too?

I think that certainly makes sense for the marketing website. There are a handful of items we do want public, like our legal changelog, but we can put those in separate repos and make the core marketing website private.

For the docs site, I think it does make sense that the docs platform repo be private, but it'd be nice to have the content be public so that users can suggest edits. So maybe this particular content being strategic is a one-off? In that case, I'm not sure where we should discuss it?

[ebeneliason]

Edits are the main reason I would want to consider keeping it public. We could theoretically detach all content from the site, but it would negatively impact the authorship workflow, and I don't think there's much that's proprietary on the platform side anyway given that we're leveraging an open source tool. Is there a particular reason to make it private, or are we just asking if there's a reason to leave it public?

[eak12913]

I've taken a look at the updates and I think we're in a good place to get things merged. @ebeneliason - do you want to sync quickly and get both your PR and this one merged and shipped?

[brikis98]

Edits are the main reason I would want to consider keeping it public. We could theoretically detach all content from the site, but it would negatively impact the authorship workflow, and I don't think there's much that's proprietary on the platform side anyway given that we're leveraging an open source tool. Is there a particular reason to make it private, or are we just asking if there's a reason to leave it public?

Reasons to make it private:

1. So we can have discussions in Issues/PRs around the content without worrying about leaking any private company details.
2. So the content is a harder to copy. This isn't really open source content we want others taking and reusing, but proprietary content to Gruntwork. I understand the website is public anyway, so you could always screen scrape it, but that's still a significantly harder step than having access to the raw, underlying Markdown.
3. So the platform is harder to copy. It is possible that the way we create the docs site is part of our differentiator in the future. I would want the underlying code that makes our docs platform possible to be private in that case.

Would it be enough to grant customers access to the content to suggest edits? So it's a private repo, but customers get access to it via Aperture, like our other repos?

[ebeneliason]

Would it be enough to grant customers access to the content to suggest edits?

That's a good idea. I think think that would strike the right balance between (hopeful) user-contributed fixes and privacy. I would keep the content private as well, in this case. I don't see any advantage to making the source content public, given that:

1. the content itself is public via the hosted site, where it's nicer to read anyway
2. it's harder to test the content if its separate, and impossible for any "public" viewer to test without the platform anyway
3. some of the differentiation noted as a reason to make it private could leak into the source itself, e.g. via React component definitions, other pre-processed syntax, etc.