Improve documentation navigation and organization

BLOGGING.md

@@ -3,6 +3,12 @@
 So you're interested in contributing to the Pulumi blog? Great! Follow these
 steps to make it happen.
 
+> **Related documentation:**
+> - [CONTRIBUTING.md](CONTRIBUTING.md) - General contribution guidelines
+> - [STYLE-GUIDE.md](STYLE-GUIDE.md) - Comprehensive style and UX standards
+> - [CODE-EXAMPLES.md](CODE-EXAMPLES.md) - Guidelines for code examples
+> - [SEO.md](SEO.md) - SEO optimization checklist
+
 ## Set Up Your Development Environment
 
 If you haven't already, clone this repository and

CLAUDE.md

@@ -0,0 +1,41 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+> **Related documentation:**
+> - [CONTRIBUTING.md](CONTRIBUTING.md) - Guide for contributing to Pulumi documentation
+> - [STYLE-GUIDE.md](STYLE-GUIDE.md) - Comprehensive style and UX standards
+> - [BLOGGING.md](BLOGGING.md) - Instructions for writing blog posts
+> - [CODE-EXAMPLES.md](CODE-EXAMPLES.md) - Guidelines for creating code examples
+> - [SEO.md](SEO.md) - Search engine optimization checklist
+
+## Essential Commands
+
+### Build and Development
+- `make ensure`: Install dependencies and build assets
+- `make build`: Build the site to ./public
+- `make serve`: Run Hugo server locally at http://localhost:1313
+
+### Validation
+- `make lint`: Check Markdown and other files for correctness
+- `make format`: Format all applicable files
+
+### Testing
+- `make test`: Run all example program tests
+- `ONLY_TEST="example-name" make test-programs`: Run a specific test
+
+### Content Creation
+- `make new-blog-post`: Generate scaffold for a new blog post
+- `make new-tutorial`: Create a new tutorial page
+- `make new-example-program`: Generate a new multi-language code example
+
+## Key Guidelines
+
+For comprehensive guidelines, please refer to the specific documentation files linked above. Here are the most critical points:
+
+- One h1 per page, use semantic line breaks
+- Place tested code examples in /static/programs/
+- Use descriptive link text (no "click here" or "here")
+- Create redirects with Hugo aliases when changing URLs
+- Follow language-specific conventions in [STYLE-GUIDE.md](STYLE-GUIDE.md)
+- Test all code examples before submitting

CODE-EXAMPLES.md

@@ -2,6 +2,11 @@
 
 Our documentation site at [pulumi.com/docs](http://pulumi.com/docs) provides a variety of code examples embedded within our doc pages to help users understand and apply Pulumi concepts. Ensuring the accuracy and reliability of these examples is essential, which is why we have automated testing available.
 
+> **Related documentation:**
+> - [CONTRIBUTING.md](CONTRIBUTING.md) - General contribution guidelines
+> - [STYLE-GUIDE.md](STYLE-GUIDE.md) - Comprehensive style and UX standards
+> - [BLOGGING.md](BLOGGING.md) - Guidelines for blog posts that might include code examples
+
 In order to get automated testing of your code example, the code must be added to a specific directory, and integrated into the document with a [Hugo shortcode](https://gohugo.io/content-management/shortcodes/). Once added, code examples are tested through an [automated pipeline](https://github.com/pulumi/docs/blob/master/.github/workflows/pull-request.yml) on a [regular cadence](https://github.com/pulumi/docs/blob/master/.github/workflows/scheduled-test.yml) to maintain ongoing accuracy.
 
 ## How it works

CONTRIBUTING.md

@@ -1,4 +1,22 @@
-# Contributing Pulumi Documentation
+# Contributing to Pulumi Documentation
+
+This guide will help you contribute to Pulumi's documentation. Use the navigation below to find what you need quickly.
+
+**Quick navigation:**
+- [Documentation Overview](#documentation-structure)
+- [Creating Links](#links-to-other-files)
+- [Hugo Tips](#hugo-tips)
+- [Style Guidelines](#style-guide)
+- [Writing Blog Posts](BLOGGING.md)
+- [Writing Code Examples](CODE-EXAMPLES.md)
+- [Style Guide (Comprehensive)](STYLE-GUIDE.md)
+
+## What would you like to do?
+
+- **Edit existing content:** Follow our [style guide](#style-guide) and use [Hugo's relref shortcode](#links-to-other-files) for internal links
+- **Add new content:** Understand our [documentation structure](#documentation-structure) and use our [Hugo tips](#hugo-tips)
+- **Test your changes:** Run `make serve` to preview changes locally at http://localhost:1313
+- **Write a blog post:** See the [blogging guide](BLOGGING.md)
 
 ## Pulumi terminology
 
@@ -51,6 +69,40 @@ Which, on a page inside the `./content/reference` directory, will generate:
 
   - **no_on_this_page** Specify this variable to prevent displaying an "On This Page" TOC on the right nav for the page.
   - **block_external_search_index** Specify this variable to prevent crawlers from indexing the page.
+
+## Testing your changes
+
+To see how your changes look locally before submitting a pull request:
+
+```bash
+# Install dependencies and build assets
+make ensure
+
+# Run the development server
+make serve
+```
+
+Then visit http://localhost:1313 to preview your changes.
+
+## Common commands
+
+```bash
+# Build the entire website
+make build
+
+# Run linting on Markdown and other files
+make lint
+
+# Format all applicable files
+make format
+
+# Run all tests
+make test
+
+# Test specific programs
+ONLY_TEST="example-name" make test-programs
+```
+
 ## Style guide
 
 ### Language and terminology styles
@@ -84,3 +136,11 @@ If a tutorial has more following tutorials, use a **Next steps** section at the
 ## Blog Post Authoring
 
 For instructions on contributing to the [Pulumi blog](https://www.pulumi.com/blog/), [see BLOGGING.md](BLOGGING.md).
+
+## Additional Resources
+
+For more detailed guidance, please refer to:
+
+- [Style Guide](STYLE-GUIDE.md) - Comprehensive style and UX standards
+- [Code Examples](CODE-EXAMPLES.md) - Guidelines for writing code examples
+- [SEO Guidelines](SEO.md) - Search engine optimization guidance

Makefile

@@ -59,7 +59,18 @@ build:
 check_links:
 	$(MAKE) banner
 	$(MAKE) ensure
-	./scripts/link-checker/check-links.sh "https://www.pulumi.com"
+	./scripts/link-checker/check-links.sh "https://www.pulumi.com" "$(SECTION)"
+
+# Usage: make check_section SECTION=/docs/
+.PHONY: check_section
+check_section:
+	@if [ -z "$(SECTION)" ]; then \
+		echo "Error: SECTION variable is required. Example: make check_section SECTION=/docs/"; \
+		exit 1; \
+	fi
+	$(MAKE) banner
+	$(MAKE) ensure
+	./scripts/link-checker/check-links.sh "https://www.pulumi.com" "$(SECTION)"
 
 .PHONY: check_search_urls
 check_search_urls:

SEO.md

@@ -1,3 +1,13 @@
+# SEO Guidelines
+
+This document provides a checklist for search engine optimization (SEO) of Pulumi documentation, blog posts, and other web content.
+
+> **Related documentation:**
+> - [CONTRIBUTING.md](CONTRIBUTING.md) - General contribution guidelines
+> - [STYLE-GUIDE.md](STYLE-GUIDE.md) - Comprehensive style and UX standards
+> - [BLOGGING.md](BLOGGING.md) - Guidelines for blog posts
+> - [CODE-EXAMPLES.md](CODE-EXAMPLES.md) - Guidelines for code examples
+
 ## SEO Checklist
 
 - [ ] Identify whether the intent of the piece is informational, preferential, navigational, or transactional

STYLE-GUIDE.md

@@ -1,10 +1,16 @@
 # Style Guide
 
-This document defines some general styles we adhere to in the docs.
+This document defines general styles and user experience (UX) standards we adhere to in the Pulumi documentation, marketing website, and registry.
+
+> **Related documentation:**
+> - [CONTRIBUTING.md](CONTRIBUTING.md) - Guide for contributing to Pulumi documentation
+> - [BLOGGING.md](BLOGGING.md) - Instructions for writing blog posts
+> - [CODE-EXAMPLES.md](CODE-EXAMPLES.md) - Guidelines for creating code examples
+> - [SEO.md](SEO.md) - Search engine optimization checklist
 
 ## Language
 
-Words are important. Pulumi strives to use language that is clear, harmonious, and friendly to all readers.  With these goals in mind, we use the following guidelines:
+Words are important. Pulumi strives to use language that is clear, harmonious, and friendly to all readers. With these goals in mind, we use the following guidelines:
 
 * Avoid ableist language:
   * Instead of _crazy_ try _wild_.
@@ -21,13 +27,18 @@ Words are important. Pulumi strives to use language that is clear, harmonious, a
 
 * Ensure that readers are able to scan the headings of a page and get an effective overview of the page's content.
 * Every page should have exactly one `h1`.
-* Headings levels should only increment one level at a time.  E.g., if your previous heading level was an `h2`, the next heading must be an `h2` or an `h3`, but not, e.g., an `h4` or `h5`.
+* Headings levels should only increment one level at a time. E.g., if your previous heading level was an `h2`, the next heading must be an `h2` or an `h3`, but not, e.g., an `h4` or `h5`.
 * Docs and registry headings should use sentence case (i.e., first letter of the first word is capitalized).
 
-## Links
+## Links and Buttons
 
 * Link text should be descriptive and have meaning outside of the surrounding context: Avoid link text like _here_, _click here_, _see here_ and instead link to the title of the linked page, e.g. "see [Pulumi Pricing](https://www.pulumi.com/pricing/)". (While this practice benefits all readers, it is of particular importance for visually impaired users who use screen readers and often jump through the links of a document.)
 * When changing the URL for an already existing page, add a redirect by using a [Hugo alias](https://gohugo.io/content-management/urls/#yaml-front-matter).
+* Use descriptive text for button labels and links, and avoid generic labels such as "Learn more."
+* Use unique labels for distinct actions - having two buttons with the same label that take different actions is confusing to users.
+* Links should take you to another page, and buttons should take an action on the page.
+* When possible, links should look like links, and buttons should look like buttons.
+* When not a special case (e.g., navigation), links should exist within the context of text.
 
 ## Notes and Warnings
 
@@ -58,6 +69,7 @@ This bit of info is serious. If you missed it, bad things could happen.
 ## Paragraphs and Line Breaks
 
 * Keep paragraphs short, rarely use 4 or more sentences in a single paragraph.
+* Use line lengths between 45 – 75 characters (this is in reference to the rendered page, not the markdown).
 
 * When writing paragraphs and long sentences, use one of the following:
 
@@ -126,13 +138,18 @@ This bit of info is serious. If you missed it, bad things could happen.
 ## Content Design
 
 * Lead with content that excites and engages, end with exactly one call-to-action.
+* Every page should have no more than one primary action.
 * Try and save links for the last 75% of the content.
 * Use headings and lists to make content scannable and consumable.
 * Use visuals: code, graphs, videos, architecture diagrams, etc.
 * Highlight important points.
 * Avoid emojis unless for notes or absolutely necessary.
 
+## Component Usage
+
+* Use existing components, or improve existing components over creating new components unless you identify a need that is not solveable with the current components.
+
 ## Additional Resources
 
 * Markdownlint will help enforce syntactically valid Markdown and is available as a [CLI tool](https://github.com/igorshubovych/markdownlint-cli#installation) or as a [Visual Studio Code plugin](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint).
-* [Writing inclusive documentation](https://developers.google.com/style/inclusive-documentation) (Google).
+* [Writing inclusive documentation](https://developers.google.com/style/inclusive-documentation) (Google).