Terragrunt: Documentation: Create terragrunt.io website

[conorgil]

I think that it would be ideal if there were a terragrunt.io website that presented the Terragrunt documentation in a format similar to the Terraform documentation available on terraform.io.

The Terragrunt README contains lots of information about how to configure and use Terragrunt, but it is very long. Creating a website modeled off of terraform.io would likely make it easier for users to find the information they need more quickly, allow Terragrunt to maintain permalinks, and provide more flexibility to add additional content on the website without the fear of making the README more dense

The Terraform README file contains a brief overview of the tool, a link to documentation on the website, and then details about to how to develop for Terraform. That might be a nice model to follow for Terragrunt.

Following the Terraform model, the Terragrunt website might include the following sections:

• What is Terragrunt?
  
  
  
  • Explain what Terragrunt is for and some basic, brief use cases.
  
  
  • Link to more detailed use-cases and additional reading (Gruntworks blog,
    
    Terraform: Up & Running, etc)
  
  
  • Make it clear that Terragrunt is maintained by Gruntworks.io and is not associated
    
    with Hashicorp
  
  
• Use cases
  
  
  
  • Have a sub-section for the detailed exploration of each use-case currently in the README
  
  
• Getting started
  
  
  
  • Terragrunt installation
  
  
  • AWS creds
  
  
  • AWS IAM policies
  
  
• Example configurations
  
  
  
  • List some of the example Terragrunt configurations for common setups
  
  
  • Link to the actual code example configurations on github. See #169.
  
  
• Downloads
  
  
  
  • Link to the Terragrunt releases on GitHub (instead of making them available via
    
    the website, at least to start)?
  
  
• Upgrade guides
  
  
  
  • List each Terragrunt upgrade guide (currently, we only have 1, but there will
    
    likely be more in the future)
  
  
• Configuration
  
  
  
  • Explain the terragrunt = {} block is expected in terraform.tfvars files
  
  
  • Somewhere in this section (or a sub-section) document each keyword available in
    
    Terragrunt configuration (e.g. include, extra_arguments, remote_state, etc, etc.
  
  
  • Load order and semantics
  
  
  • Explain where terragrunt looks for the configuration to be defined.
  
  
  • Link to the docs on --terragrunt-config
  
  
  • Configuration syntax
  
  
  • Explain that Terragrunt uses HCL just like Terraform and link to the Terraform docs
  
  
  • Interpolation syntax
  
  
  • Explain that Terragrunt uses the same interpolation syntax as Terraform
    
    and link to the Terraform docs
  
  
  • Document each of the built in functions. This would be a short definition similar to the
    
    Terraform built in functions, but it would likely make sense to link to the Terragrunt use-cases
    
    documentation and/or examples for additional details.
  
  
  • Make it clear that Terragrunt built in functions are only interpolated inside of a
    
    terragrunt = {} block and that Terraform does not process interpolation syntax within
    
    terraform.tfvars files.
  
  
  • Environment variables
  
  
  • Explain how it can be useful to share a value between Terraform and Terragrunt using
    
    environment variables. Link to Terraform docs on env vars
  
  
• Commands (CLI)
  
  
  
  • Explain that terragrunt passes most commands and flags directly to Terraform
  
  
  • Document the terragrunt commands plan-all, apply-all, destroy-all, output-all, etc
  
  
  • Document all terragrunt CLI options --terragrunt-*
  
  

The website could be maintained in this same repo in a website/ directory like the terraform website source.

The Terraform license seems favorable to reusing some of its website structure, but we could (should) of course get in touch with them to give them a heads up on the Terragrunt site and agree on branding that makes it clear to users that Terragrunt is a different tool than Terraform and is not maintained by Hashicorp.

Thoughts?

[dpetzel]

I like this idea

[brikis98]

This is a great idea. Doing it with GitHub pages would make it easy to launch and manage the site.

[brikis98]

BTW, I'm happy to buy the domain and configure the repo to publish GitHub pages to it... Not sure we have time at the moment to build the website itself though. PRs for that would be very welcome :)

Also, as an alternative to the Terraform docs layout, we could also use any of the themes already available for GitHub Pages, such as these: https://pages.github.com/themes/

[conorgil]

@brikis98 I think that github pages requires the site to be maintained in a repo called username.github.io. See docs here.

This would require us to maintain the documentation in a different repo than the source code. In my experience, that situation creates a huge disincentive to update the documentation appropriately as the source code changes. Maintaining the documentation and the source code in a single repo makes it easier to enforce that PRs include all items on the "PR checklist" before merging: code, tests, documentation, etc.

Thoughts on the documentation being in a separate repo using GitHub pages vs following the model Terraform uses and maintaining it in a single repo? Let me know if GitHub pages can accomplish having the documentation in a single repo with the source code and I'm just not aware that it can do that.

[dpetzel]

A separate repository wouldn't be necessary. You're example is for a user site, but this would be a project site: https://help.github.com/articles/user-organization-and-project-pages/#project-pages.

[conorgil]

@dpetzel Ah! Thanks for the link. That sounds like exactly what we're looking for if we configure a custom domain name with it. Makes sense to me to give it a shot and see how it works out!

@brikis98 I'm up for working on the site over the next few weeks. Thoughts on the best way to get started? I could build out the site locally using Jekyll and push it to my fork.

[brikis98]

@conorgil Doing it with a fork sounds perfect!

[conorgil]

Sounds good. I will likely comment on this thread occasionally with updates as things move along over the next few weeks.

[conorgil]

In case anyone is following this thread, I've been pulled into other projects for the past few weeks and traveling quite a bit during the summer, so I have not made much progress on this. Hopefully, I can get back to it in the fall once my travel schedule lets up a bit.

[josh-padnick]

@conorgil Thank you for the update and your great work so far. You've really improved the onboarding experience for Terragrunt users!

[davidbegin]

@conorgil I am working on migrating an existing terraform setup to using terragrunt and am spending all my time reading the docs anyway, so I would like to help in your noble efforts!

How can I pitch in?

[conorgil]

@davidbegin Thanks for reaching out. Unfortunately, my time has gotten pulled completely into an unrelated project and I haven't made any progress on the documentation site yet. If you get started, comment back on this thread and I'd love to help out once I get some bandwidth down the road.

[davidbegin]

Ok thanks @conorgil I'll see what I can get started and post back here.

[davidbegin]

I took a first pass of moving the docs into Github Pages | Code

I used the minimal-mistakes Jekyll theme and did not customize anything. Because of this, there are some various styling issues, that could be fixed by pulling the theme in and customizing.

As someone who is new to Terragrunt and just refactored a large project to use Terragrunt,
I tried to use my beginner mindset and recent experience to organize the docs in a way that made since to me, however there are probably lots of sections that still need rewriting and refinement.

I kept mostly the same structure as the current README, and divided the site into 3 main sections:

• Quick Start (which I think would take the place of the current README)
• Use Cases
• Terragrunt Details

Then in each section, if there were a lot details, I added sub-navigation to help single page navigation (https://davidbegin.github.io/terragrunt/use_cases/keep-your-terraform-code-dry is an Example of this.) I also added more examples and rewrote some various sections to make them more clear as I went along.

Couple Random Notes:

• There is a lot of duplicated setup in the navigation.yml, which I think there is a way to fix with Jekyll, but my first couple attempts didn't work, so I punted on the issue.
• I had to do this work on my Forked version's master branch, to get it to work with Github-Pages.

I would love any feedback or direction on how to proceed!

[conorgil]

@davidbegin This looks like a fantastic start. I've often found that getting over that initial hurdle and having something in place allows others to more easily contribute and make it better. Lower barrier to entry.Thanks for taking the first step on this!

I wish that I could contribute to this in the short term, but unfortunately I won't have time to work on Terragrunt for the foreseeable future. I started bootstrapping my own company ~2 months ago, which is taking all of my time.

I definitely plan to contribute back to this effort down the road once I come back to building out infra on AWS again. Hopefully, someone else can jump in and help you tackle the website effort because I think it would really improve the UX of Terragrunt, especially for new users.

[brikis98]

@davidbegin Wow, awesome! Thanks for getting the ball rolling on that :)

Some thoughts/questions/feedback in no particular order:

1. It would be great to make the landing page called "home" with subsections "intro", "quick start", "basic usage", and "installation." You already have the latter three, so it's just a matter of adding an intro section before them that introduces what Terragrunt is and why it exists in a couple sentences. It could have links to the GitHub repo too. You could also add "Home" as a 3rd top-level link in the nav at the top of the page.

2. I'm not a huge fan of the minimal-mistakes theme. How does this look with something like the minimal theme?

3. I found the left nav a bit confusing, as it doesn't give a sense of hierarchy. You click on a use case and the "use cases" part of the nav remains, but all the other parts change, and it's not obvious where you are or how to get back. Perhaps the solution is to have a consistent left nav where the subsections expand (similar to readthedocs)? That would also help keep the code DRY. It may also help to have breadcrumbs at the top of each page (e.g., Use Cases / DRY Terraform Code / Remote COnfiguration).

Thanks!

[davidbegin]

Awesome, thank you for all the feedback, I will start making these changes!

Also I was wondering if I should I keep posting updates here, or if I should open PR and continue conversation there?

[brikis98]

A PR would be great!

[chenrui333]

👍 Where are we with this issue?

[conorgil]

@chenrui333 it looks like https://github.com/gruntwork-io/terragrunt/pull/392 was opened as a WIP PR. Last commit was ~1 year ago, so I'm guessing folks (myself included) didn't have time to carry this through to completion yet.

[chenrui333]

What are the materials that help us to build the website? Do we have terragrunt.io for use?

[josh-padnick]

I just purchased terragrunt.io and terragrunt.com. We'd be happy to make those available to anyone who wants to create a website for the project!

[rondemena]

@josh-padnick you should "Documentation" as Code approach it just like the Terraform Web-site and stand up a GitHub docs template inside this repo for documentation, and all the supporting content to go in under a /docs folder. "Read-the-docs" templates are fairly easy to being initial composition behind.

[josh-padnick]

I'm not sure I follow completely. The Terraform Website repo looks like it's build around a static site generator, (Middleman). Read The Docs is a separate service.

Are you just suggesting that we should create the main site content here in this repo? If so, that sounds like a good idea to me. A PR here would be most welcome, though I'd strongly encourage any contributors to take an RDD approach so that everyone can give feedback on the approach before we go too far down a particular direction.

[davidbegin]

I started the PR originally a yearish ago, and then life got very busy, and I sadly left my work abandoned. However, if some others have some time, I can help out as well.

[rondemena]

I'm not sure I follow completely. The Terraform Website repo looks like it's build around a static site generator, (Middleman). Read The Docs is a separate service.

Are you just suggesting that we should create the main site content here in this repo? If so, that sounds like a good idea to me. A PR here would be most welcome, though I'd strongly encourage any contributors to take an RDD approach so that everyone can give feedback on the approach before we go too far down a particular direction.

I agree with the RDD approach - so if someone wants to compose the README into an appropriate docs/ folder structure and we can get the "repo owner" in gruntworks to change the repo to support GitHub pages in the docs/ folder, its a very simple fix - all the existing README.md remains intact until the site has completely been composed and accepted.

[mcalhoun]

we can get the "repo owner" in gruntworks to change the repo to support GitHub pages in the docs/ folder

No problem. @josh-padnick (above) is one of the Gruntwork co-founders. He, @brikis98 or I can all get DNS setup and update the repo to support GitHub pages...that's the simple part... ;)

[lae]

Just want to point out that I found David's ghpages site via a search engine, and was wondering if it was official or not since the text looked familiar. I'm guessing others may be, too, but the documentation there is probably out of date (which may be a concern).

[brikis98]

Ah, thanks for the heads up, I didn't realize that site existed. We have it on our roadmap this quarter to create an official Terragrunt website to replace the giant README with something far more readable. Stay tuned.

[reegnz]

@brikis98 will it still happen this quarter? Didn't happen in the previous one. :) Sorry for the bad joke.

Jokes aside, I would be willing to pick up parts of this topic, but there needs to be some planning first, so current efforts in documenting new features don't collide too much with moving the docs around. We should keep the changes incremental, not refactoring the docs and rolling out a static website all in a single PR.The single PR approach didn't happen previously because it was too ambitious in it's goal and wanted static website and doc refactoring in a single PR.

Let's do baby steps instead:

1. Start refactoring the docs in a docs folder, README should be minimized to the bare essentials.
2. Start refactoring the docs into a format that is compatible with a static site generator.
3. Introduce the static site generator.

I think no1. and no2. are essential in making this process incremental, otherwise it never gets done (see past 2 years conversations not doing that but wanting to refactor the docs big-bang style).

[brikis98]

@reegnz We had it in our plans, and had even planned putting it on gruntwork.io/terragrunt so we could add it to an existing website rather than a new one to reduce the work, but still ran out of time before we got to it.

Breaking up the work into smaller steps is a great idea. The root README could be reduced to:

1. A sentence or two explaining what Terragrunt is
2. A quick start showing concisely a few core use cases (e.g., see Terragrunt: how to keep your Terraform code DRY and maintainable)
3. Install instructions
4. Links to more documentation on all the other features, with each link going to a separate Markdown file.
5. Contribution guidelines
6. License

A PR for something like that is very welcome!

[yorinasub17]

This is now done in terragrunt.gruntwork.io.