Update Docs - Remove Screenshots, Reorganize content, Fix style concerns

[laurapacilio]

What

Reworking some parts of the documentation to make navigation easier/break up the huge index page of content. Also removing all screenshots in anticipation of Unified Navigation effort.

Specifically, this PR does the following:

• Removes all screenshots of the Terraform Cloud UI. First, we're about to embark on a large revamp of the UI, per the Unified Cloud navigation effort, so all screenshots will be out of date. Second, screenshots are difficult to maintain as the product evolves and are often not necessary for users. I do not believe these screenshots are necessary to convey what users need to do --> our UI is pretty intuitive and the processes involving cloud agents are relatively simple UI interactions. Therefore, I removed the screenshots to improve the maintenance burden of this content in the future.
• Breaks up the Overview page: In the current documentation, almost all information about agents is within one long Overview page. This presents a few disadvantages. For users, it creates long pages that are a bit overwhelming to parse. It also does not advertise what users can actually do with agents or tell users what to expect from the content. "Overview" is such a broad term and conveys that we'll provide an overview of agents. If users are looking specifically for requirements, they may not find them as quickly as they could if we break the content up into separate logical pages. For us, long pages like this will continue to get longer and more complex as the product evolves. By breaking these pages up, we help create a better user experience and we give ourselves room to scale the documentation set (beyond just making a longer and longer page) as the product evolves over time.
• Fixes style issues: I tried not to re-write all the content, as that's excessive. But I did reword some of it to make UI elements bold instead of using "", remove unnecessary notes/blend them with the text so that we call out important elements for users in the right places, and removes some passive voice and future language (e.g. the product will do x) that does not align with our style guide.
• Reorganizes the sidebar & renames some pages: In addition to adding new pages for Requirements, Installing & Running Agents, etc. I renamed the Hooks page and changed the order of pages. My thought is that it's not immediately obvious to new users what "Hooks" are for, so creating a sidebar heading that explains this could be helpful for new users. I also changed "Monitoring" to "Logging" as Logging is a term we use throughout other Terraform documentation and this page contains information about various log messages. I also reorganized the pages in the sidebar so that they flow in a logical fashion --> requirements, then install, then set up in TFC, then logging, and finishing with lesser used pages like telemetry and changelog. Before, we went from overview to Telemetry --> Hooks was not grouped with other functionality about how to actually use agents.

Why

Cloud Agents are really great, and I want to make sure the docs are structured in the best way to serve users. These changes should help improve the user experience, improve the maintainability of these docs, and also help them adhere to the style guidelines we're implementing across the rest of the Terraform documentation set.

Screenshots

Before

After

---

TODO: Add redirects in terraform-website for key headings that were moved, e.g. "Scoping Agents to Specific Workspaces". These may be linked from places in the TFC docs and we want to make sure we don't break those links for users.

---

Merge Checklist

If items do not apply to your changes, add (N/A) and mark them as complete.

Pull Request

• One or more labels describe the type of change (e.g. clarification) and associated product (e.g. tfc).
• Description links to related pull requests or issues, if any.

Content

• Redirects have been added for moved, renamed, or deleted pages. This requires a separate PR in the terraform-website repository redirects.next.js file.
• API documentation and the API Changelog have been updated.
• Links to related content where appropriate (e.g., API endpoints, permissions, etc.).
• Pages with related content are updated and link to this content when appropriate.
• Sidebar navigation files have been updated for added, deleted, reordered, or renamed pages.
• New pages have metadata (page name and description) at the top.
• New images are 2048 px wide. They have HashiCorp standard annotation color (#F92672) and format (rectangle with rounded corners), blurred sensitive details (e.g. credentials, usernames, user icons), and descriptive alt text in the markdown for accessibility.
• New code blocks have the correct syntax and line breaks to eliminate horizontal scroll bars.
• UI elements (button names, page names, etc.) are bolded.
• The Vercel website preview successfully deployed.

Reviews

• I or someone else reviewed the content for technical accuracy.
• I or someone else reviewed the content for typos, punctuation, spelling, and grammar.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
terraform-docs-agents	✅ Ready (Inspect)	Visit Preview	Aug 31, 2022 at 7:24PM (UTC)

[mgarrell777]

@laurapacilio Thanks very much for these edits. I have some wording suggestion changes. But overall, these edits look good to me.

[ryanuber]

Looks good to me! Made a few suggestions and updates but otherwise this seems accurate.

[ryanuber]

LGTM! 🚢