Consolidate readmes and contribution guidelines

.github/PULL_REQUEST_TEMPLATE.md

@@ -20,16 +20,3 @@ Please cherry-pick my commits into:
 * [ ] Foreman 3.10/Katello 4.12
 * [ ] Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
 * We do not accept PRs for Foreman older than 3.9.
-
-#### Review checklists
-
-Tech review (performed by an Engineer who did not author the PR; can be skipped if tech review is unnecessary):
-
-* [ ] The PR documents a recommended, user-friendly path.
-* [ ] The PR removes steps that have been made unnecessary or obsolete.
-* [ ] Any steps introduced or updated in the PR have been tested to confirm that they lead to the documented end result.
-
-Style review (by a Technical Writer who did not author the PR):
-
-* [ ] The PR conforms with the team's style guidelines.
-* [ ] The PR introduces documentation that describes a user story rather than a product feature.

CONTRIBUTING.md

@@ -1,39 +1,31 @@
 # Contributing to Foreman Documentation
 
-Foreman community welcomes all feedback, issues, pull requests (PRs), and reviews.
-Every contributor has different backgrounds, interests, and experiences with Foreman and its open source community.
-
-We give ourselves these guidelines to collaborate and contribute to Foreman documentation more efficiently.
-It helps everyone to set expectations, communicate conventions, and ensures happy collaborative work across organisations and backgrounds.
-We respect each others time and energy spent on Foreman documentation.
-
-## Maintainers
-
-* help less experienced community members with git, Github, PRs, asciidoc, and asciidoctor.
-* expect a basic effort in contributions, including the [pull request template](PULL_REQUEST_TEMPLATE.md) being filled out.
-* only merge PRs if the Github Actions are green.
-For an overview of what to expect from editorial review, see [Red Hat peer review guide for technical documentation](https://redhat-documentation.github.io/peer-review/#checklist).
-* read the proposed change and make friendly and helpful comments.
-* ping community members with more experience if they are unsure about specific details.
-* try to review PRs in a timely manner.
-* keep non-trivial PRs open for at least 24 hours (72 hours if over the weekend) to allow for input from the community.
-Examples of trivial PRs: Fixing a typo, fixing markup, or fixing links.
-Non-trivial PRs might not only benefit from additional review but they also represent an opportunity for community members to ask questions and learn.
+If you need help to get started, open an issue, ask the docs team on [Matrix](https://matrix.to/#/#theforeman-doc:matrix.org), or ping [`@docs`](https://community.theforeman.org/g/docs) on the [Foreman Community Forum](https://community.theforeman.org/).
+
+## Contributor's pledge
+
+As a contributor, I will:
+
+* Familiarize myself with the [Pull Request Checklist](#Pull-Request-Checklist) and [Foreman documentation minimalist style guide](#Foreman-documentation-minimalist-style-guide).
+* Open additional issues if my contribution is incomplete.
+
+## Maintainer's pledge
 
-## Contributors
+As a maintainer, I will:
 
-* are able to make meaningful contributions to the Foreman documentation, regardless of their experience with git, asciidoc, writing documentation, or Foreman.
-* familiarize themselves with the [Pull Request Checklist](#Pull-Request-Checklist).
-* open additional issues if a contribution is incomplete.
-* are invited to review other PRs.
+* Help less experienced community members with git, Github, PRs, asciidoc, and asciidoctor and make friendly and helpful comments.
+* Only merge PRs if the Github Actions are green.
+* Try to review PRs in a timely manner.
+* Keep non-trivial PRs open for at least 24 hours (72 hours if over the weekend) to allow for input from the community.
+Examples of trivial PRs: Fixing a typo, fixing markup, or fixing links.
+Non-trivial PRs might not only benefit from additional review but they also represent an opportunity for community members to ask questions and learn.
 
-## Pull Request Checklist
+## Pull request checklist
 
-* [ ] I am familiar with the conventions as specified in the [guides/README.md](guides/README.md) file.
 * [ ] Before pushing, I view my diff against master or the target branch and check for spelling mistakes, failed conflict resolutions, etc.
 * [ ] Before pinging others about my PR, I await the Github Actions to see if my branch builds.
 * [ ] If I add text that applies only to a specific downstream product, I notify others and give them a chance to request extending the `ifdef::[]` or `ifndef::[]` directive.
-+ [ ] My change does not contain `Foreman`, `Satellite`, or `orcharhino`.
+* [ ] My change does not contain `Foreman`, `Satellite`, or `orcharhino`.
 Instead, I use attributes.
 * [ ] I don't add useless or trailing white space.
 * [ ] I put each sentence to its own line.
@@ -48,8 +40,145 @@ See [LICENSE](LICENSE).
 * [ ] I am familiar to proper capitalization for project-specific terminology.
 See [Capitalization](#Capitalization).
 * [ ] The first line of the file contains the modular docs content type attribute, for example, `:_mod-docs-content-type: ASSEMBLY` for assemblies.
+* [ ] I fill out the cherry-picking list in the PR template to the best of my abilities to signify which versions my update applies to.
+If unsure, I let reviewers know so that they can assist.
+
+Each PR should undergo tech review.
+(Tech review is performed by an Engineer who did not author the PR. It can be skipped if the PR does not significantly change description of product behavior.)
+
+* [ ] The PR documents a recommended, user-friendly path.
+* [ ] The PR removes steps that have been made unnecessary or obsolete.
+* [ ] Any steps introduced or updated in the PR have been tested to confirm that they lead to the documented end result.
+
+Each PR should undergo style review.
+(Style review is performed by a Technical Writer who did not author the PR.)
+
+* [ ] The PR conforms with the team's style guidelines.
+* [ ] The PR introduces documentation that describes a user story rather than a product feature.
+
+## Foreman documentation minimalist style guide
+
+### Code conventions
+
+Use the following markup conventions:
+
+* Source files use UTF-8 character encoding.
+* Source files use [AsciiDoc](https://docs.asciidoctor.org/asciidoc/latest/) syntax.
+* A single line only contains one sentence.
+Please do not wrap lines by hand.
+This makes `git diff` much easier to read and helps when reviewing changes.
+* No trailing whitespace on lines and in files.
+Whitespace after partial files has to be handled in the file using the `include::` directive.
+* User input is surrounded by underscores (`_`) to indicate variable input, for example, `hammer organization create --name "_My Organization_" --label "_my_organization_"`.
+* Links to different guides are followed by the title of the guide in italics, for example `in _{ManagingHostsDocTitle}_`.
+
+### Images
+
+Each guide must have an `images/` subdirectory with `images/common` symlink into the `common/images/` directory.
+Images local to the guide shall be kept in the `images/` directory.
+Images which are supposed to be reused across guides shall be kept in the `images/common/` directory.
+Subdirectories can be created and are actually recommended.
+
+To insert an image, use `image::common/global_image.png` or `image::local_image.png`.
+
+You should create upstream diagrams using [diagrams.net](https://www.diagrams.net/).
+Place the editable diagram in `drawio` format in `guides/image-sources/`.
+For inclusion in the content, export diagrams to SVG and place them as described above.
+
+### Using AsciiDoc attributes
+
+The content in this repository is shared between the upstream Foreman community and branded downstream products such as Red Hat Satellite and orcharhino by ATIX.
+Therefore, never write "Foreman", "Satellite", or "orcharhino" words directly, but use the following attributes:
+
+| Attribute | Upstream value | Downstream by Red Hat | Downstream by ATIX |
+| -------- | -------------- | --------------------- | ------------------ |
+| {Project} | Foreman | Satellite | orcharhino |
+| {ProjectName} | Foreman | Red Hat Satellite | orcharhino |
+| {ProjectServer} | Foreman server | Satellite Server | orcharhino Server |
+| {SmartProxy} | Smart Proxy | Capsule | orcharhino Proxy |
+| {SmartProxyServer} | Smart Proxy server | Capsule Server | orcharhino Proxy Server |
+
+Every build uses common base attributes, more are defined in the build specific attribute files:
+
+* [attributes.adoc](common/attributes.adoc): version definitions and includes for other attribute files.
+* [attributes-base.adoc](common/attributes-base.adoc): base attributes common for all builds.
+* [attributes-foreman-el.adoc](common/attributes-foreman-el.adoc): base overrides for foreman-el build.
+* [attributes-foreman-deb.adoc](common/attributes-foreman-deb.adoc): base overrides for foreman-deb build.
+* [attributes-katello.adoc](common/attributes-katello.adoc): base overrides for katello build.
+* [attributes-satellite.adoc](common/attributes-satellite.adoc): base overrides for satellite build.
+* [attributes-orcharhino.adoc](common/attributes-orcharhino.adoc): base overrides for orcharhino build.
+
+By default, attributes cannot be used in shell or code examples.
+To use them, use the "attributes" keyword:
+
+	[options="nowrap" subs="+quotes,attributes"]
+	----
+	# ls {AttributeName}
+	----
+
+Avoid using phrases like "Starting from version 6.5 or 1.22" because it is not possible to easily translate these strings into all build variants.
+
+#### Conditional content
+
+If a piece of your content, such as a block, paragraph, warning, or chapter, is specific for a certain [build](#builds), use special build attributes to show or hide it.
+
+To show a piece of content only for the `katello` build:
+
+	ifdef::katello[]
+	NOTE: This part is only relevant for Foreman with the Katello plugin.
+	endif::[]
+
+To hide a piece of content for `katello` that will be shown for all other builds:
+
+	ifndef::katello[]
+	NOTE: This part is relevant for Foreman without the Katello plugin, but also Satellite and orcharhino.
+	endif::[]
+
+Use comma for logic "or":
+
+	ifdef::katello,satellite[]
+	NOTE: This part is only relevant for deployments with Katello plugin or in Satellite environment.
+	endif::[]
+
+Some files are included in different contexts, there are attributes to find the correct context.
+In these cases use both `ifdef` and `ifeval`:
+
+	ifdef::foreman-el,foreman-deb[]
+	ifeval::["{context}" == "{project-context}"]
+	* A minimum of 4 GB RAM is required for {ProjectServer} to function.
+	endif::[]
+	endif::[]
+
+
+### File structure
+
+If you create a new file, use the file structure described here.
+
+Documentation in this directory follows a modular structure described in the [Modular documentation reference guide](https://redhat-documentation.github.io/modular-docs/).
+To write new documentation, you can use [modular documentation templates](https://github.com/redhat-documentation/modular-docs/tree/main/modular-docs-manual/files) or copy an existing file from `guides/common/modules/` and adapt it.
+
+Included files are kept in the `common/` subdirectory and have prefixes to distinguish their type of content.
+
+Assemblies are kept at the top of the `common/` subdirectory:
+
+* [`assembly`](https://redhat-documentation.github.io/modular-docs/#forming-assemblies): Files starting with `assembly_` contain user stories and the modules required to accomplish those user stories.
+See the [assembly template](https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc).
+
+Modules are kept in the `common/modules/` subdirectory:
+
+* [`con`](https://redhat-documentation.github.io/modular-docs/#creating-concept-modules): Files starting with `con_` contain concepts and explain the _what_ and _why_.
+Their first line contains the `:_mod-docs-content-type: CONCEPT` attribute.
+See the [concept template](https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc).
+* [`proc`](https://redhat-documentation.github.io/modular-docs/#creating-procedure-modules): Files starting with `proc_` contain procedures and explain _how_ to achieve a specific goal.
+Their first line contains the `:_mod-docs-content-type: PROCEDURE` attribute.
+See the [procedure template](https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc).
+* [`ref`](https://redhat-documentation.github.io/modular-docs/#creating-reference-modules): Files starting with `ref_` contain references and append other files, for example tables with options.
+Their first line contains the `:_mod-docs-content-type: REFERENCE` attribute.
+See the [reference template](https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc).
+* [`snip`](https://redhat-documentation.github.io/modular-docs/#using_text_snippets_or_text_fragments_writing-mod-docs): Files starting with `snip_` contain snippets that are reused throughout multiple guides, for example admonitions.
+Snippets must not contain an ID.
 
-## Capitalization
+### Capitalization
 
 All headings are sentence case.
 We capitalize the following terms:
@@ -89,7 +218,7 @@ We do not capitalize the following terms:
 * remote execution
 * subscription
 
-## Further Information
+### Further Information
 
 * [Contributing Guidelines for Github documentation](https://github.com/github/docs/blob/main/CONTRIBUTING.md)
 * [theforeman.org/contribute](https://theforeman.org/contribute.html)

README.md

@@ -7,24 +7,30 @@ This Git repository contains the following documentation:
 
 For official Foreman documentation, see [Foreman Manual](https://theforeman.org/manuals/latest/index.html).
 
-## Contributing
+Foreman community welcomes all feedback, issues, pull requests (PRs), and reviews.
+Every contributor has different backgrounds, interests, and experiences with Foreman and its open source community.
 
-Contributions are welcome.
-Please, familiarize yourself with [CONTRIBUTING](CONTRIBUTING.md) and [Contribution Guidelines for Foreman guides](guides/README.md#contribution-guidelines).
+We give ourselves these guidelines to collaborate and contribute to Foreman documentation more efficiently.
+It helps everyone to set expectations, communicate conventions, and ensures happy collaborative work across organizations and backgrounds.
+We respect each others time and energy spent on Foreman documentation.
 
-## Repository content
+Familiarize yourself with [CONTRIBUTING](CONTRIBUTING.md) before you start contributing.
 
-### Foreman guides
+## Repository contents
 
-For information on working with the Foreman guides, see the [README in the `guides/` subdirectory](guides/README.md).
-
-### Static site
+### `web/` subdirectory
 
 The landing page for [docs.theforeman.org](https://docs.theforeman.org) is available as a generated static site.
 The static content is always built from the `master` branch.
-See [README in the `web/` subdirectory](web/README.md) for more information.
+See [README in the `web/` subdirectory](web/README.md) for more information, including information on locally testing the site.
+
+### `guides/` subdirectory
+
+The sources for documentation are available as AsciiDoc files.
+The guides are based on the [modular documentation framework](https://redhat-documentation.github.io/modular-docs/).
+See the [README in the `guides/` subdirectory](guides/README.md) for more information, including instructions on locally building individual guides.
 
-## Testing the site locally
+### Global `Makefile` to build both static side and guides
 
 To build both the static site and the guides for easy local testing, a global `Makefile` is provided in the root directory with the following targets:
 
@@ -40,8 +46,6 @@ This builds all contexts, so the initial build might be slow.
 For faster builds on modern multi-core machines, use the `-j` option.
 Stable versions are symlinks to the nightly (current) version, which can cause issues for deleted (or renamed) guides.
 
-For instructions on locally building only the guides, see [Building locally](https://github.com/theforeman/foreman-documentation/blob/master/guides/README.md#building-locally).
-
 ## Deployment
 
 GitHub actions perform HTML (with link validation) and WEB artifact creation and if succeeded and branch is master or stable, artifacts are downloaded, extracted and deployed (commited into gh-pages). Deployment does not delete files, in order to remove some unwanted content, manual deletion and push into gh-pages must be performed.
@@ -60,6 +64,8 @@ When a commit is pushed into `X.Y`:
 
 ## Branching a new release
 
+When a new Foreman version is branched, the Foreman release owner ensures that a new branch for documentation is created.
+
 * On `master`, pull the latest changes and create a new `X.Y` branch.
 * On the `X.Y` branch:
   * Update `guides/common/attributes.adoc`.