WIP: Docs- Add landing page & URL redirect info

Fix typo

Enhance content

enhancements

enhancements

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

@@ -4,34 +4,101 @@ 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.
+Outlines the recommended steps for successfully contributing to the Quarkus documentation.
 
 == Prerequisites
 
-Quarkus docs use AsciiDoc, a lightweight markup language.
+Quarkus docs are sourced in AsciiDoc, a lightweight markup language.
 
 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, use the *Content types* section in xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference].
++
+. 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 root of the `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>
+----
++
+{important-caption}
+
+<1> Set the `id` value to be the same as the file name but without the extension.
+<2> For information about how to create a good title for the content type, see xref:doc-reference.adoc[Quarkus documentation reference].
+<3> The `_attributes.adoc` include is required to ensure that attributes get resolved, the ToC displays, 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].
++
+. Optional: If you have renamed the filename of an existing AsciiDoc file, see xref:doc-contribute-docs-howto#redirect-an-existing-Quarkus-AsciiDoc-file[Redirect an existing Quarkus AsciiDoc file].
+
+For more information about the minimum header requirements, see xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference].
+
+== 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 the 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,
+we recommend that you build the `docs` module locally, run the Vale linter as outlined below, and view resulting output before submitting your changes for review.
 
 include::{includes}/compile-quarkus-quickly.adoc[tag=quickly-install-docs]
 
@@ -128,4 +195,14 @@ correcting the usage of a term, correcting a recurring error, or moving common c
 - 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 automatically runs on all PRs that are submitted to the repository.
+If the docs that you contribute do not align with the key style or terminology preferences of our Quarkus community, you will see a suggestion, warning, or error on the diff tab.
+To ensure that your content gets approved, fix the errors that are flagged.
+
+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` and the doc SMEs will take a look.