Backport of Consul Documentation restructure according to IA & content strategy into release/1.21.x#22318
Closed
hc-github-team-consul-core wants to merge 3 commits intorelease/1.21.xfrom
Closed
Conversation
|
Thank you for your submission! We require that all contributors sign our Contributor License Agreement ("CLA") before we can accept the contribution. Read and sign the agreement Learn more about why HashiCorp requires a CLA and what the CLA includes 1 out of 2 committers have signed the CLA.
temp seems not to be a GitHub user. Have you signed the CLA already but the status is still pending? Recheck it. |
github-team-consul-core-pr-approver
previously approved these changes
May 5, 2025
Collaborator
github-team-consul-core-pr-approver
left a comment
github-team-consul-core-pr-approver
left a comment
There was a problem hiding this comment.
Auto approved Consul Bot automated PR
…22041) * migration * nav fixes * nav * Missing top-level pages * nav/content alignment * partial path update * Partial fixes * Partial updates * partial paths * erroneous replacement fix * 3 page migration (test) * /agent migration * CA, cluster peering, & config entries * connect -> Gateways * connect * connect * nav * Dynamic app config * ecs * Tutorials -> docs * Tutorials moved * Updated nav with tutorials in docs * enterprise, install, and k8s through k8s/connect * k8s deployment * finished k8s migration * lambda, nia, nomad * nav fixes * security and discovery * service & upgrade * final page migrations * Nav update * Change navigation and page placement * Revert "Change navigation and page placement" This reverts commit 0934235. * Change navigation and page placement * Fixed broken include. * Updated sync consul service catalog with aws cloud map page. * Update to match page use of cloud map - AWS separates the two words. * Updated register services into a namespace docs page. * Updated explore the consul ui page. * Refactor HAProxy tutorial into usage doc * re-org * architecture and fundamentals * duplicate page deleted * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Moved consul-aws cli reference to its own page. * partial fix * Fix links and next steps * install and dev mode pages * CodeBlocks * env var page * title changes * Aligning with tracker * nav fixes * tracking alignment * Nav fixes * content checker fixed * Partial path fixes * more partial fixes * remove v2 reference * nav/title adjustments * first 64 find and replaces * /connect and /consul-vs-other * through /nia * finish docs paths * tutorial link paths * Redirects * Redirect updates * another tutorials redirect fix * link path updates * security architecture * Raft backend architecture * Deploy Consul overview * Fixes to redirect tests * Redirects * More redirect fixes * Updated link path replacements * README draft * README * More readme * Readme * Deploy server overview * Deploy client agents and dataplanes * cloud auto join page move * Manage Consul * Clean up * Consul template structure and first content * page name and filepath changes * Index updates * typo * VMs index page * Consul template documentation * disaster recovery and openshift guides (#11) * docs: disaster recovery * docs: openshift * adding OpenShift Local to CRC naming convention * Openshift page restructure * add redundancy-zones link * update openshift guide versions Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: boruszak <jeffrey.boruszak@hashicorp.com> Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * /connect * /connect/vm * /connect/k8s * /fundamentals/cli * /fundamentals/cli and /register/service/nomad * /fundamentals/api * /fundamentals/editions (and remove env-var) * /fundamentals/tf and finish /fundamentals/editions * /fundamentals/identity * Fixes for working preview * Fundamentals updates * Agent page updates * Agent reference restructure * Redirects update * CT config * References with links and defaults * Some workflow fixes * Fix some links and images * Gossip and TLS with vault first changes * Gossip and TLS with vault first changes * Replace consul.io for URL deprecation * Bug Bash fixes * More bug bash fixes * nav fix * Final bug bash fixes * Vault TLS consul-template * Name the tool Consul Template * Move auto_config in config reference * Fix links * Updates to architecture * Architecture and use case updates * QoL improvements * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Glossary improvements * Updates * README updates * Finetuning * final readme updates * Link path changes to fix 500 errors * linkcheck fixes round 2 * round 3 500 error fixes * Errors fixes round 4 * CE-827: adding k8s and openshift tshoot info * Revert "CE-827: adding k8s and openshift tshoot info" This reverts commit a02f21d. * Redhat category rename * Readme updates * CE-846 content and screenshots * Ref/agent remove index; add auto-config file * Fix broken links due to configuration-file dir * CE-851 content and images * Fix content-check errors * lock update + move autopilot * v1.21 updates & release notes * IA/Content strategy readme finalizations * Inline image fix * real img fix * More README + consul.d in agent fundamentals * reviewed dataplane architecture content * review rest of completed drafts in arch * persona/directory index * reviewed fundamentals * Readme toc and final updates * re-order some sections * Final toc for readme * move inline examples to Example section where it made sense. * Ce-835: DNS views (#16) * CE-835 DNS forwarding in OpenShift * CE-835 DNS views in OpenShift * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --------- Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * CE-827: Troubleshoot OpenShift (#17) * CE-827: adding k8s and openshift tshoot info * CE-827: adding openshift import-image info * CE-827: import-image timeout * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --------- Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * CE-833: OpenShift page updates (#18) * CE-833: updater versions * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --------- Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * CE-825: Consul on OpenShift Index Page (#19) * CE-825: Consul on OpenShift Index Page * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --------- Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * telemetry * configuration file index * ESM and release notes updates * Apply suggestions from code review Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> * fixes for content check * partial fix * Merge resolution changes * Agent: Fix remaining links to reference/agent# * Copy edits * Update HAProxy load balance guide * review manage/dns * multi-tenant/sameness-group/vm * multi-tenant/samenessgroup/k8s * secure * deploy * CE-834: Upgrade OpenShift (#25) * upgrade openshift deployment * openshift: improve upgrade article * openshift: add redhat word to openshift term * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * revision after code review --------- Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Cleanup, especially Agent references * content fixes * Error fix --------- Co-authored-by: Daniele Carcasole <daniele@daniele-tt72xnn9y7.homenet.telecomitalia.it> Co-authored-by: danielehc <daniele@hashicorp.com> Co-authored-by: Anthony <russo555@gmail.com> Co-authored-by: Krastin Krastev <krastin@hashicorp.com> Co-authored-by: danielehc <40759828+danielehc@users.noreply.github.com> Co-authored-by: Aimee Ukasick <aimee.ukasick@hashicorp.com> Co-authored-by: Tu Nguyen <im2nguyen@gmail.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
boruszak
approved these changes
May 5, 2025
4 tasks
Contributor
|
Addressed in #22319 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Backport
This PR is auto-generated from #22041 to be assessed for backporting due to the inclusion of the label backport/1.21.
🚨
The person who merged in the original PR is:
@boruszak
This person should manually cherry-pick the original PR into a new backport PR,
and close this one when the manual backport PR is merged in.
The below text is copied from the body of the original PR.
Description
This PR updates the Consul documentation to refresh its structure according to a defined information architecture (IA) and content strategy.
There are three components to this documentation restructure. They exist as a complementary set and cannot be implemented individually.
website/contentthat formally defines Consul in relation to the documentation structure. This document declares a product taxonomy for Consul and controls vocabulary to standardize content.Advantages of this information architecture
Mental model improvements. This IA is designed to make Consul less complicated for existing users and easier for new users to learn. It organizes the documentation according to the type of content so that explanations, usage instructions, and reference documentation are more rigorously maintained as discrete categories. The IA and content strategy README also includes explicit definitions for terms in a product taxonomy and controlled vocabularies. These assets “map” where the product runs to better articulate Consul’s control plane and data plane operations alongside application infrastructure, and the IA adopts the cardinal directions to describe Consul’s network operations as occurring in north/south and east/west directions. Sequencing usage phases that are divided into “Consul operations” and “service networking” categories provides additional clarity for product operations to support a user’s ability to build a “mental model” of Consul. This mental model advances the level of educational objectives we can achieve according to Bloom’s taxonomy by providing a foundation for users to more effectively “apply” and “analyze” what they learn about Consul.
Modularity and interoperability. This information architecture and content strategy apply the Diataxis framework for technical documentation to our defined product personas, jobs-to-be-done, and critical user journeys. The result is a more modular approach to product documentation that leverages recognized strategies and workflows for producing maintainable content. And even though it was designed for a docs-as-code workflow, the IA includes a taxonomy that makes exporting to other frameworks relatively straightforward. For example, moving to Darwin Type Information Architecture (DITA), or migrating to a dedicated Content Management System (CMS), would not require significant redesign effort because the directory and file naming schema converts directly into the topic “tags” that these other systems require, while the README index taxonomic categories to one another.
Google SEO improvements. Previous efforts to improve our content’s Google SEO focused on rewriting page descriptions, expanding the capabilities of DevDot’s search capabilities, and addressing 4xx and 5xx errors on the site to patch known problems. But according to Google’s SEO guide on site organization, breadcrumbs represented by the URL structure play an outsized role in content SEO, to the point where Google provides best practices for structuring URLs. Following these best practices to structure our data is the part of the SEO equation that we can affect most directly, and represents the highest effort/highest impact changes we can make to improve our performance on Google Search.
Deployment preview
Stable deployment preview
PR Checklist
Overview of commits