awsdocs · geoffcline · Jan 20, 2025 · Jan 20, 2025 · Jan 20, 2025 · Jan 20, 2025
@@ -19,11 +19,20 @@ You can now edit the EKS Docs directly on GitHub. Our streamlined process includ
 
 We look forward to your contributions.
 
-*To edit a single page from a web browser*
+include::edit-single-web.adoc[leveloffset=+1]
+
+include::edit-web.adoc[leveloffset=+1]
+
+include::vale-github.adoc[leveloffset=+1]
+
+include::vale-local.adoc[leveloffset=+1]
+
+include::create-page.adoc[leveloffset=+1]
+
+include::insert-link.adoc[leveloffset=+1]
+
+include::create-content-q.adoc[leveloffset=+1]
+
+include::pr-preview.adoc[leveloffset=+1]
 
-. Navigate to the page in the EKS User Guide
-. Select *Edit this page on GitHub* in the right sidebar
-. Open the GitHub editor: press `e` or select *Edit in Place* from the pencil icon dropdown menu
-. Make your edits, and then select *Commit changes...*
-** Confirm your email and include a short description of the changes
 
@@ -0,0 +1,49 @@
+[.topic]
+[#create-content-q]
+= Create docs content with Amazon Q
+:info_titleabbrev: Create with Amazon Q
+
+You can use Amazon Q to create and revise docs content. This is an easy way to get started on a new page. Amazon Q is available as an extension to Visual Studio (VS) Code. 
+
+In the following image, Amazon Q generated the lines marked with green.
+
+image::images/contribute-q.png["Amazon Q in VS Code"]
+
+== Install Amazon Q with VS Code
+
+1. Open VS Code
+2. Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
+3. Search for "Amazon Q"
+4. Click Install on the Amazon Q extension
+5. Wait for installation to complete
+6. Restart VS Code when prompted
+
+== Login to Amazon Q 
+
+1. After installing, click the Amazon Q icon in the VS Code activity bar
+2. Click "Sign in to Amazon Q"
+3. Enter your {aws} credentials when prompted
+4. Once authenticated, you'll see the Amazon Q chat interface
+
+== Use Amazon Q to create content
+
+1. Open the file you want to edit in VS Code
+2. Select the text you want to revise or the location for new content
+3. Press *Ctrl+I* or *Cmd+I*
+4. In the prompt, be specific about:
+   * The type of content you need
+   * The target audience
+   * Key points to cover
+   * Desired tone and style
+5. Review the generated content in the inline preview
+6. Use *enter* to accept the changes, or *esc* to reject them.
+7. Edit further as needed
+
+== Tips
+
+* Start with a simple request and iterate to get the content you want.
+* Create a first draft of the page headings, then ask Q to fill them in. 
+* Amazon Q may output Markdown. This is fine. The AsciiDoc tooling can understand most markdown syntax. 
+
+To learn more about Amazon Q Developer, see link:amazonq/latest/qdeveloper-ug/q-in-IDE.html["Using Amazon Q Developer in the IDE",type="documentation"].
+
@@ -0,0 +1,35 @@
+[.topic]
+[#create-page]
+= Create a new page
+:info_titleabbrev: Create page
+
+
+Learn how to create a new docs page. This topic includes instructions for creating the initial page metadata, and adding the page to the guide table of contents. 
+
+== Create page
+
+. Navigate to the chapter directory. For example, if you want to create a new page in the "Security" section, navigate to the `latest/ug/security` directory. 
+. Determine the page ID. By convention, the page ID is all lowercase and seperated with `-`. The ID of this page is `create-page`.
+. Create a new file with the page ID and the `adoc` extension. For example, `create-page.adoc`.
+. Insert the page metadata using this template:
+
+image::images/contribute-new-page.png["New page metadata"]
+
+
+== Add page to navigation
+
+. Navigate to the parent page. The parent page of top level sections is `book.adoc`.
+. At the bottom of the parent page, include the child page.
++
+[source]
+====
++++include::${filename}[leveloffset=+1]+++
+====
++
+_For example:_
++
+[source]
+====
++++include::create-page.adoc[leveloffset=+1]+++
+====
+
@@ -0,0 +1,59 @@
+[.topic]
+[#edit-single-web]
+= Edit a single page from a web browser
+:info_titleabbrev: Edit single page
+
+You can easily edit a single page in the EKS User Guide directly through your web browser.
+
+image::images/contribute-web-edit.png["View of GitHub web edit interface"]
+
+If you want to edit multiple pages from your web browser, see <<edit-web>>.
+
+== Prerequisites
+
+* Docs page to change opened in web browser
+* Signed into GitHub
+
+== Procedure
+
+. Navigate to the page you want to edit in the EKS User Guide documentation
+
+. Look for the *Edit this page on GitHub* button located in the right sidebar of the page
+
+. Once on GitHub, open the editor by either:
+** Pressing the `e` key on your keyboard
+** Clicking the pencil icon and selecting *Edit in Place* from the dropdown menu
+** If you don't have the option to edit, you need to login to GitHub. Your GitHub account does not need any special permissions to suggest changes. However, internal Amazon contributors should link their GitHub profile. 
+
+. Make your desired changes to the content in the GitHub editor
+** The editor provides syntax highlighting and preview capabilities
+** You can use AsciiDoc markup to format your changes
+** You can use `ctrl-f` to open a find/replace interface.
+
+. (Optional) Preview your changes. 
+** Use the `preview` tab to preview your changes with rich formatting.
+** Use the `show diff` option to highlight changed sections. Removed sections have a red indicator in the left margin. New sections have a green indicator in the left margin.
+
+. When finished editing, click the *Commit changes...* button at the top of the editor
+
+. In the commit dialog:
+** Verify your email address is correct
+** Add a brief but descriptive commit message explaining your changes
+** Optionally add a longer description if needed
+** Select to create a new branch and pull request
+
+You have created a pull request including the proposed changes.
+
+== Pull Request Overview
+
+When you create a PR:
+
+* Your changes are submitted for review by repository maintainers
+* Reviewers can comment on your changes and request modifications
+* Automated tests may run to validate your changes
+* Once approved, your changes can be merged into the main repository
+
+Pull requests help ensure quality and provide a way to discuss changes before they are integrated.
+
+https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews[Learn how pull requests are reviewed and approved in the GitHub Docs.]
+
@@ -0,0 +1,31 @@
+[.topic]
+[#edit-web]
+= Edit multiple files from a web browser with the GitHub Web Editor
+:info_titleabbrev: Edit files with GitHub
+
+If you want to propose change to multiple pages, or create a new docs page, use the GitHub.dev web editor. This web editor is based on the popular Visual Studio Code text editor. 
+
+image::images/contribute-web-dev.png["GitHub.dev web editor user interface]
+
+== Prerequisites
+
+* Logged in to GitHub
+* Familiarity with Visual Studio Code editor
+* Familiarity with Git
+
+== Procedure
+
+NOTE: The EKS Docs team has created a workspace file that includes suggested configurations for the editor, such as text wrapping and AsciiDoc syntax highlighting. We suggest you load this workspace file. 
+
+. Open the https://github.dev/awsdocs/amazon-eks-user-guide/blob/mainline/eks-docs.code-workspace?workspace=true[workspace] on GitHub.dev
+** You can bookmarl the URL `https://github.dev/awsdocs/amazon-eks-user-guide/blob/mainline/eks-docs.code-workspace?workspace=true`
+. (First time setup only) You may be propted to create a fork of the repo in your own GitHub account. Accept this prompt. For more information, see https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks[About forks] in the GitHub docs. 
+. (First time setup only) Accept the prompt in the bottom right to install the AsciiDoc extension. 
+. Navigate to the docs content at `latest/ug`
+** Docs files are organized by their top level section. For example, pages in the "Security" chapter have source files under the "security/" directory. 
+. To view a preview of a docs page, use the *Open preview to the Side* button in the top right. The icon includes a small magnifying glass. 
+. Use the *Source Control* tab in the left to commit your changes. For more information, see the Visual Studio Code docs:
+** https://code.visualstudio.com/docs/sourcecontrol/overview#_commit[Commit changes]
+** https://code.visualstudio.com/docs/sourcecontrol/github#_creating-pull-requests[Create a pull request] 
+
+After you create a pull request, it will be reviewed by the docs team. 
@@ -0,0 +1 @@
+../images
@@ -0,0 +1,33 @@
+[.topic]
+[#insert-link]
+= Insert a link
+:info_titleabbrev: Insert link
+
+AsciiDoc supports multiple types of links. Using the right link type is important so the link works properly in different environments.
+
+== Link to a page or section in the EKS User Guide
+
+Use cross references (xref) to link between pages/sections within the same documentation site, such as the EKS User Guide. They automatically update if the target section moves or is renamed. 
+
+=== Define custom link text
+
+`xref` `:section-id[${link-text}]`
+
+=== Use page title as link text
+
+Use the section ID surrounded by angle brackets. For example `<<` `page-id>>`.
+
+== Link to another page in the {aws} Docs
+
+. Find the link to the {aws} Docs page
+. Remove the `https://docs.aws.amazon.com/` prefix, keeping only the path. The path should start with an a-z character. 
+. Create a link as shown below
+
+`link` `:AmazonS3/latest/userguide/create-bucket-overview.html["Create a bucket", type="documentation"]`
+
+== Link out to the internet
+
+This format creates a standard link out to the internet. Use this for Non-Amazon content or content on GitHub. 
+
+`link` `:https://example.com[Visit Example Site]`
+
@@ -0,0 +1,40 @@
+[.topic]
+[#pr-preview]
+= View a preview of pull request content
+:info_titleabbrev: View PR Preview
+
+The EKS User Guide GitHub is configured to build and generate a preview of the docs site. This preview doesn't have the full {aws} theme, but it does check the content builds properly and links work.
+
+image::images/contribute-preview.png["GitHub comment with preview URL"]
+
+This preview is hosted at a temporary URL by {aws} Amplify. 
+
+== View Preview
+
+When you submit a pull request, {aws} Amplify attemps to build and deploy a preview of the content.
+
+If the build succeeds, *aws-amplify-us-east-1* comments the preview link on the pull request.
+
+If the build fails, the repo admins can see the logs and provide feedback.
+
+NOTE: If you haven't contributed before, a project maintainer may need to approve running the build.
+
+== Preview limitations
+
+The preview is built as a single large HTML file. It will be displayed as multiple pages when published. 
+
+*What works:*
+
+* Cross references (`xref`)
+* Links to the internet
+* Images
+* Content hosted from `samples/`
+
+*What doesn't work:*
+
+* Links to other {aws} content, links with `type="documentation"`.
+** This content doesn't exist in the preview environment.
+* The variable `aws` will not display properly. The value of this changes based on the environment.
+
+
+
@@ -0,0 +1,75 @@
+[.topic]
+[#pr-status]
+= View the status of your GitHub Pull Request (PR)
+:info_titleabbrev: View PR Status
+
+After you create a pull request, you can track it's status. Pull requests have three important statuses: merged, closed, and changes requested. 
+
+If a pull request is merged, the changes were accepted. It may take a few hours for the website to update. If the PR was closed, please understand we appreciate the contribution but could not approve the changes. For example, we may have been unable to replicate the problem. If a pull request has changes requested, review the feedback and update the pull request. 
+
+include::images/contribute-pr.png["View PR feedback"]
+
+== View the pull requests you created
+To view pull requests you created:
+
+. Go to the GitHub repository
+. Click the "Pull requests" tab
+. Select *Filters* and then *Your pull requests*
+. Review the list of your open pull requests
+
+== View pull requests assigned to you 
+To view pull requests assigned to you for review:
+
+. Go to the GitHub repository
+. Click the "Pull requests" tab
+. Select *filters* and then *assigned to you*
+. Review the list of pull requests awaiting your review
+
+== Review a pull request
+
+Learn how to https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request[review a pull request] in the GitHub Docs.
+
+== Make further changes on a pull request
+
+If changes are requested on a pull request, you can make further changes in the pull request.
+
+{aws} suggests using the GitHub.dev web editor to make further changes to a pull request. This supports viewing PR comments inside the text editor. 
+
+=== Make further changes with a web browser
+
+. Use the `.` (period) key to open the pull request in the GitHub web editor
+. Review the comments and make changes in the text editor. You can mark comments as resolved from within the editor. 
+. Use the *source control* menu in the left sidebar to commit the changes, which updates the PR. 
+
+=== Make further changes locally
+
+Use the GitHub CLI to pull the changes locally.
+
+==== Setup GitHub CLI
+
+. Install the GitHub CLI if you haven't already:
+  * For macOS: `brew install gh`
+  * For Windows: `winget install GitHub.cli`
+  * For Linux: Follow instructions at https://github.com/cli/cli#installation
+
+. Authenticate with GitHub:
+  * Run `gh auth login`
+  * Follow the prompts to complete authentication
+
+==== Checkout pull request
+
+. Check out the pull request branch:
+  * Run `gh pr checkout <PR-NUMBER>`
+  * Replace <PR-NUMBER> with your pull request number
+  * The pull request number is visible at the top of the PR
+  * This creates a local branch with the PR changes
+
+. Make your changes locally using your preferred text editor
+
+. Commit and push your changes:
+  * Stage changes: `git add .` 
+  * Commit changes: `git commit -m "your commit message"`
+  * Push to GitHub: `git push`
+
+The pull request will automatically update with your new changes. 
+
@@ -0,0 +1,26 @@
+[.topic]
+[#vale-github]
+= View style feedback online for a pull request
+:info_titleabbrev: View PR feedback
+
+When you create a pull request to propose docs changes, multiple GitHub actions run. This includes a style check using Vale.
+
+image::images/contribute-style-web.png["View style feedback on GitHub"]
+
+The style check:
+
+* Returns an error if the string "AWS" is used instead of the variable `{aws}`
+** Pull requests cannot be merged until this is resolved.
+* Adds style comments to the pull request. 
+
+== View style feedback
+
+. Open your Pull Request
+** https://github.com/awsdocs/amazon-eks-user-guide/pulls[View a list of open pull requests]
+. Select the *Files changed* tab
+. Feedback from Vale is visible as line comments, that start with `[vale]`.
+** Use the style feedback to identify typos, spelling errors, and awkward phrasing. 
+
+When you update a pull request, the Vale check runs again. 
+
+Learn how to https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#making-changes-to-files-in-your-pull-request[Make changes to files in your pull request] in the GitHub docs.