Merge pull request quarkusio#30043 from michelle-purcell/QDOCS-70-DOC…

…-CONTRIBUTING

Enhance doc contributor guide with information about creating new content, landing page config, and URL redirection

docs/src/main/asciidoc/doc-contribute-docs-howto.adoc

@@ -4,34 +4,96 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 [id="doc-contribute-howto"]
-= How to contribute documentation
+= Contribute to Quarkus documentation
 include::_attributes.adoc[]
 :categories: contributing
 :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/]
 
-Outline the recommended steps for making successful contributions to Quarkus documentation.
+Contribute to the documentation by using the recommended steps, workflow, and style guidance to ensure the content successfully renders on the Quarkus website portal.
 
 == Prerequisites
 
-Quarkus docs use AsciiDoc, a lightweight markup language.
+Quarkus docs use link:https://asciidoc.org/[AsciiDoc] markup.
 
 We suggest you have the following materials nearby:
 
 - An editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin.
 - The https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc syntax reference]
-- The xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference] for required syntax and other conventions.
+- The xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference] for the required syntax, preferred style, and other conventions.
 
-== Sources
+== Locate the source files for Quarkus docs
 
 - AsciiDoc files are in the `src/main/asciidoc` directory within the `docs` module of the {quarkus-base-url}/tree/main/docs[Quarkus GitHub repository].
 - Configuration documentation is generated from JavaDoc comments in Java source files.
 - Java, YAML, and other source files can also be xref:doc-reference.adoc#reference-source-code[referenced] by AsciiDoc files.
+- The link:https://quarkus.io/guides/[Quarkus documentation] menu page, also known as the doc index page, is sourced in the link:https://github.com/quarkusio/quarkusio.github.io[quarkusio.github.io] repository.
+
+
+== Create Quarkus content in AsciiDoc
+
+To ensure that your content shows up correctly on the link:https://quarkus.io/guides/[Quarkus documentation home page], use the following steps:
+
+. Decide on a content type that best fits the content that you are contributing.
++
+TIP: To help you decide, see the content type descriptions in xref:{doc-guides}/doc-reference.adoc#titles-and-headings[Titles and headings] on the "About Quarkus documentation" page.
++
+. Go to the `src/main/asciidoc/_templates` directory, and make a copy of the relevant template for the content type you have chosen. Be sure to:
+** Use the filename syntax of`<category>-<titlekeyword>-<titlekeyword>-<content-type>.adoc`. For example, `security-basic-authentication-tutorial.adoc`.
+** Save the file to the `docs/src/main/asciidoc` folder in the `quarkus` repository.
+. Set the minimum required header information as outlined in the following example:
++
+[source,asciidoc]
+----
+[id="security-basic-authentication-howto"] <1>
+= Secure a Quarkus application with basic authentication <2>
+include::_attributes.adoc[] <3>
+:categories: security <4>
+----
++
+<1> Set the `id` value to be the same as the file name but without the extension. You can shorten this if the file name is too long.
+<2> For information about how to create a good title for each content type, see xref:{doc-guides}/doc-reference.adoc#titles-and-headings[Titles and headings] on the "About Quarkus documentation" page.
+<3> The `_attributes.adoc` include is required to ensure that attributes get resolved, the table of contents is generated, and content renders in the website portal. 
+<4> Set at least one category to ensure that the content is findable on the link:https://quarkus.io/guides/[Quarkus documentation home page].
+
+For more information about the minimum header requirements, see xref:{doc-guides}/doc-reference.adoc#document-structure[Document structure] on the "About Quarkus documentation" page.
+
+== Retire and redirect an existing Quarkus AsciiDoc source file
+
+As content evolves, you might want to restructure an existing piece of Quarkus content into one or more content types and retire the existing AsciiDoc source file.
+
+If you are retiring or renaming a published Quarkus AsciiDoc source file, ensure that the restructure does not break existing bookmarks and links to original content. 
+Configure a URL redirect in the link:https://github.com/quarkusio/quarkusio.github.io/[Quarkus.io Website] GitHub repository by using the following steps:
+
+. Switch to the link:https://github.com/quarkusio/quarkusio.github.io/tree/develop/_redirects/guides[quarkusio/quarkusio.github.io] repository, and open the `_redirects/guides` folder.
+. Create a redirection file in Markdown format with a filename that matches the original AsciiDoc source filename that you want to retire. 
+. Add the following contents to the Markdown redirection file:
++
+[source,markdown]
+---
+permalink: /guides/<original_asciidoc_filename>/index.html // <1>
+newUrl: /guides/<new_asciidoc_filename> // <2>
+---
++
+Where:
+<1> Is the name of the original AsciiDoc source file that you are retiring.
+<2> Is the name of the AsciiDoc source file that you want to redirect to.
+
+.Example
+
+[Attributes]
+|===
+|Name of original AsciiDoc source file |Name of file to redirect to| Example pull request
+
+|`security-getting-started`
+|`security-overview-concept`
+|link:https://github.com/quarkusio/quarkusio.github.io/pull/1579[PR #1579]
+
+|===
 
 == Preview and build Quarkus documentation
 
 AsciiDoc syntax highlighting and the preview provided by an IDE may be enough for minor documentation changes.
-For significant changes or updates to generated configuration documentation,
-you should build the `docs` module and view resulting output before submitting your changes for review.
+When you make significant changes or updates to generated configuration documentation, build the `docs` module locally and run the Vale linter as outlined below.
 
 include::{includes}/compile-quarkus-quickly.adoc[tag=quickly-install-docs]
 
@@ -42,6 +104,8 @@ This will produce:
 - YAML files containing metadata for all documents individually (`docs/target/indexByFile.yaml`) and grouped by document type (`target/indexByType.yaml`). 
 - YAML files that list metadata errors by file (`docs/target/errorsByFile.yaml`) and by error type (`docs/target/errorsByType.yaml`)
 
+Review the resulting output and fix any issues before you submit your changes in a PR for review.
+
 As you make changes, you can rebuild the `docs` module specifically to update the generated HTML:
 
 [source,shell]
@@ -101,7 +165,7 @@ See the https://vale.sh/manual/[Vale CLI Manual] for details.
 
 === Vale IDE plugins
 
-https://vale.sh/docs/integrations/guide/[Vale IDE integrations] rely on installation the Vale CLI.
+https://vale.sh/docs/integrations/guide/[Vale IDE integrations] require the Vale CLI to be installed.
 
 Each has it's own configuration requirements. The Visual Studio Code IDE extension, for example, requires two workspace settings:
 
@@ -120,12 +184,22 @@ Submit your proposed changes to the core Quarkus docs by {gh-pull-requests-fork}
 
 Reviews for code and documentation have different (but overlapping) participants.
 To simplify collaborative review, either isolate changes to docs in their own PRs,
-or ensure that the PR has a single, focused purpose For example:
+or ensure that the PR has a single, focused purpose. For example:
 
 - Create a single PR that adds a configuration option for an extension and updates related materials (how-to, reference) to explain the change.
 - Create a single PR for related changes to a group of documents, some examples:
 correcting the usage of a term, correcting a recurring error, or moving common content into a shared file.
 - If there are extensive code changes and documentation changes,
 create a separate PR for the documentation changes and include the relationship in the issue description.
 
-Pull requests that contain changes to documentation will have the `area/documentation` label added automatically.
+Pull requests that contain changes to documentation will have the `area/documentation` label added automatically.
+
+== Automatic style checking on the PR diff
+
+The Vale linter job automatically runs when a PR is created or updated.
+If your content updates do not align with the key style or terminology preferences of the Quarkus community, the updated line on the diff tab gets annotated with the Vale suggestion, warning, or error.
+To ensure that your content gets approved, fix the linter errors, warnings, and suggestions.
+
+We welcome your feedback on the Quarkus documentation style guidelines.
+
+If you disagree with the Vale results, be sure to add the yellow PR label `needs-vale-rule-tweak`.