[release-1.8] RHIDP-2135: README update (redhat-developer#1517)

Co-authored-by: Fabrice Flore-Thébault <[email protected]>
Co-authored-by: deerskindoll <[email protected]>

Author: 3 people

README.adoc

@@ -1,26 +1,147 @@
 # Red Hat Developer Hub documentation
 
-This repo is the upstream mirror of https://gitlab.cee.redhat.com/red-hat-developers-documentation/rhdh
+This is a repository for Red Hat Developer (RHDH) documentation.
 
-Contribute to this repo and merged changes will be synced to gitlab for build with Pantheon. 
+## Contributing
+
+Contribute to this repository to add new and edit existing RHDH documentation published on the link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/[Red Hat Documentation page].
+
+Before submitting a pull request (PR), create a Jira issue associated with your contribution to this repository.
+
+There are currently three Jira projects related to RHDH:
+
+* link:https://issues.redhat.com/projects/RHDHBUGS[RHDHBUGS] - For issues related to existing content.
+* link:https://issues.redhat.com/projects/RHIDP[RHIDP] - For new features related to the core platform, including security mechanisms.
+* https://issues.redhat.com/projects/RHDHPAI[RHDHPAI] - For new features related to plugins and AI.
+
+Choose a Jira project that matches your contribution and create a new issue:
+
+. In the Jira project, click *Create*.
+. In the *Description* field, describe your contribution.
+. In the *Component/s* field, select *Documentation* from the drop-down list.
+. Save the created Jira issue.
+
+[IMPORTANT]
+====
+RHDH release notes are single-sourced from the *Release Notes Text* field in the Jira Epic.
+If you want to make changes to release notes, you must make them in Jira.
+Check the link:https://docs.google.com/document/d/1X2CrrU9K3ZqbxN7DXmU6P1mY7inLD32qs3rpOUHz6Vw/edit?tab=t.0#heading=h.yqxd252ryhua[RHDH Release Notes process document] for more information.
+====
+
+## Style and formatting
+
+All contributions are in AsciiDoc.
+
+Make sure your writing follows the rules
+listed in link:https://www.ibm.com/docs/en/ibm-style[IBM Style] and link:https://redhat-documentation.github.io/supplementary-style-guide/[Red Hat supplementary style guide].
+
+[NOTE]
+====
+If the IBM Style and the Red Hat supplementary style guide offer conflicting solutions,
+the Red Hat supplementary style guide solution overrides IBM Style.
+====
+
+Follow the link:https://redhat-documentation.github.io/modular-docs/[Modular documentation reference guide]
+to modularize your content.
 
 ## Building locally
 
 . Install `asciidoctor` - see https://docs.asciidoctor.org/asciidoctor/latest/install/linux-packaging/
-. Run `build/scripts/build.sh` to generate html with images in titles-generated/ folders
+. Install Podman - see https://podman.io.
+. Run the following command to generate html with images in titles-generated/ folders by using `ccutil` in a container.
+The `ccutil` CLI tool reproduces the behavior of the production publication chain (Pantheon), including its limitations, and is therefore preferred over using a more recent `asciidoctor` CLI version.
++
+[source,terminal]
+----
+$  build/scripts/build-ccutil.sh
+----
+
+[NOTE]
+====
+* To build with `asciidoctor` rather than `ccutil`, run the following script.
+The output will look differently and you might miss issues with content that cannot build in production.
++
+[source,terminal]
+----
+$  build/scripts/build.sh
+----
+====
+
+## Checking for broken links
+
+You can run `htmltest` locally to check for broken links in your PR.
+
+. Install `htmltest` from https://github.com/wjdp/htmltest
+. Run the following command:
++
+[source,terminal]
+----
+$ htmltest
+----
+
+You can run `linkchecker` to check for broken links in the published RHDH docs.
+
+. Install `linkchecker` from https://github.com/linkchecker/linkchecker.
+. Run the following command to create a .txt file with a list of detected broken links:
++
+[code,terminal]
+----
+$ linkchecker --check-extern --output failures --file-output failures/broken-links.txt https://docs.redhat.com/en/documentation/red_hat_developer_hub/<version>
+----
 
 ## Previews
 
-Commits to this repo can be seen as GH Page content here: 
+You can view commits to this repo as GitHub Page content here:
 
 https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/
 
-Pull requests will have a link to the generated HTML attached a comment.
+PRs have a link to the generated HTML attached as a comment.
 
-## Contributing
+## Reviews
+
+All PRs are reviewed for technical accuracy by an SME and writing quality by another tech writer.
+
+When possible, request a tech review first and implement suggestions from the SME.
+After your PR is approved by the tech reviewer, follow it up with a request a peer review.
+
+Check link:https://docs.google.com/spreadsheets/d/1X1KHZx2Kvbotie-sU1g2xNt5vHWtc8Wq9Zb43JycOlA/edit?gid=1375268335#gid=1375268335[this doc] for the current peer review roster.
+
+## Merging PRs
+
+After the peer and tech reviewer approve your PR, the PR is ready for merging and cherry-picking by a gatekeeper.
 
-Submit a pull request against this repo.
+Check link:https://docs.google.com/spreadsheets/d/1X1KHZx2Kvbotie-sU1g2xNt5vHWtc8Wq9Zb43JycOlA/edit?gid=0#gid=0[this doc] for the current gatekeeper roster.
 
+## Labels
 
-## Plugins Reference Guide 
+As you work on your contribution to this repo,
+use labels to show the status of your PR and to request reviews:
+
+* draft: `do-not-merge/work-in-progress`
+* ready for peer and technical reviews: `do-not-merge/review-in-progress`
+* request for a tech review: `technical-review-needed`
+* completed tech review: `technical-review-done`
+* request for a peer review: `peer-review-needed`
+* completed peer review: `peer-review-done`
+* ready for merging: `ready-to-merge`
+
+[NOTE]
+====
+Remember to remove labels as they become outdated.
+For example, remove the `do-not-merge/work-in-progress` label when you finalize your draft and your PR is ready for review.
+====
+
+## Publishing pipeline
+
+This repo is the upstream mirror of the GitLab RHDH repo https://gitlab.cee.redhat.com/red-hat-developers-documentation/rhdh
+
+Merged PRs are synced to GitLab for build with Pantheon.
+
+## Plugins Reference Guide
 For Plugin configuration guide, see upstream content in https://github.com/janus-idp/backstage-plugins/tree/main/plugins
+
+## Additional sources
+
+* link:https://spaces.redhat.com/spaces/RHDEVDOCS/pages/467060194/RHDH+documentation+contributor+guide[RHDH documentation contributor guide]
+* link:https://spaces.redhat.com/spaces/RHDEVDOCS/pages/494635174/Content+creation+guidelines [RHDH content creation guidelines]
+* link:https://spaces.redhat.com/spaces/RHDEVDOCS/pages/580260123/GitHub+Labels+-+What+When+Who[RHDH GitHub labels]