From 46cb0d50b89119bed96a44d48a2676a80d3984d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Thu, 18 Sep 2025 19:20:44 +0200 Subject: [PATCH 01/14] Restructure main readme --- CONTRIBUTING.md | 7 ------- README.md | 30 ++++++++++++++++++------------ 2 files changed, 18 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0f113d3733..1520d224300 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,5 @@ # 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. diff --git a/README.md b/README.md index 94b1fd244ae..0d725149f2a 100644 --- a/README.md +++ b/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 organisations and backgrounds. +We respect each others time and energy spent on Foreman documentation. -## Repository content +Familiarize yourself with [CONTRIBUTING](CONTRIBUTING.md) and [Contribution Guidelines for Foreman guides](guides/README.md#contribution-guidelines) 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 released, 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`. From e88bedfd38aa32f93c52f2ec739644afec3a21c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Thu, 18 Sep 2025 19:22:20 +0200 Subject: [PATCH 02/14] Clarify that a procedure is in a different readme --- web/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/web/README.md b/web/README.md index 9d152acd40f..66d105b51ca 100644 --- a/web/README.md +++ b/web/README.md @@ -20,9 +20,10 @@ To perform a HTML validation check: $ bundle exec nanoc check -Navigate to `http://localhost:3000` to test the result. To test full site with -guides, use the Makefile in the root directory. +Navigate to `http://localhost:3000` to test the result. To edit the main menu, navigate to content/js/nav.js and edit the file, publish the changes and all guides and pages will dynamically load the menu from the data structure. + +To test full site with guides, use the Makefile in the root directory. See [README](../README.md) for more information. From 876b3ea65c3dbc85de7e424a18ff2ba1c7d5b8eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Thu, 18 Sep 2025 19:27:06 +0200 Subject: [PATCH 03/14] Clean up 'contributing' --- CONTRIBUTING.md | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1520d224300..297a8d7915b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,24 @@ # Contributing to Foreman Documentation -## Maintainers +## Contributor's pledge -* 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. +As a contributor, I will: + +* Familiarize myself with the [Pull Request Checklist](#Pull-Request-Checklist). +* Open additional issues if my contribution is incomplete. -## Contributors +## Maintainer's pledge -* 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. +As a maintainer, I will: + +* 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. From 6ba54dd23fd8c4c15f67ca07b288b5758a4adad9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Thu, 18 Sep 2025 19:26:53 +0200 Subject: [PATCH 04/14] Create 'minimalist style guide' --- CONTRIBUTING.md | 140 +++++++++++++++++++++++++++++++++++++++++++++-- README.md | 2 +- guides/README.md | 133 +------------------------------------------- 3 files changed, 138 insertions(+), 137 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 297a8d7915b..29cb737b97b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ As a contributor, I will: -* Familiarize myself with the [Pull Request Checklist](#Pull-Request-Checklist). +* 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 @@ -20,7 +20,6 @@ Non-trivial PRs might not only benefit from additional review but they also repr ## 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. @@ -40,7 +39,140 @@ See [LICENSE](LICENSE). 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. -## Capitalization +## Foreman documentation minimalist style guide + +### Contribution guidelines + +Please read these guidelines before opening a Pull Request. +For more information, see [Guidelines for Red Hat Documentation](https://redhat-documentation.github.io/). + +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/). + +If you are unsure into which guide you should place your content, have a look at the `docinfo.xml` files within each `doc-*` directory. + +### 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 and aim to follow [AsciiDoc Mark-up Conventions for Red Hat Documentation](https://redhat-documentation.github.io/asciidoc-markup-conventions/). +* 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. +* Image file names use dashes (`-`) and suffix a build target, for example, `foreman`. +See also [Images](#Images). +* 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}_`. +* The first line of a file contains the modular docs content type attribute, for example, `:_mod-docs-content-type: ASSEMBLY` for assemblies. +The content type reflects the file prefix: `ASSEMBLY`, `PROCEDURE`, `CONCEPT`, or `REFERENCE`. +The only exceptions are `master.adoc` files, which do not require this attribute. + +### 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 | + +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_. +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. +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, e.g. tables with options. +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, e.g. admonitions. +Snippets do not require an ID. + +### Capitalization All headings are sentence case. We capitalize the following terms: @@ -80,7 +212,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) diff --git a/README.md b/README.md index 0d725149f2a..930ce99a7ae 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ We give ourselves these guidelines to collaborate and contribute to Foreman docu 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. -Familiarize yourself with [CONTRIBUTING](CONTRIBUTING.md) and [Contribution Guidelines for Foreman guides](guides/README.md#contribution-guidelines) before you start contributing. +Familiarize yourself with [CONTRIBUTING](CONTRIBUTING.md) before you start contributing. ## Repository contents diff --git a/guides/README.md b/guides/README.md index 9f2d6c46deb..ba8313e0384 100644 --- a/guides/README.md +++ b/guides/README.md @@ -147,138 +147,7 @@ File names that are missing from this JSON file would be omitted from the TOC. Currently the main use of the TOC file is for downstream links validation in [`foreman_theme_satellite`](https://github.com/RedHatSatellite/foreman_theme_satellite/commit/7fb213daa8929b1e5ceb7999a79dbc8eebd3500d). In order to implement the same technique for the upstream documentation, there is need to extract links from the code. -## Contribution guidelines - -Please read these guidelines before opening a Pull Request. -For more information, see [Guidelines for Red Hat Documentation](https://redhat-documentation.github.io/). - -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/). - -If you are unsure into which guide you should place your content, have a look at the `docinfo.xml` files within each `doc-*` directory. - -### 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 and aim to follow [AsciiDoc Mark-up Conventions for Red Hat Documentation](https://redhat-documentation.github.io/asciidoc-markup-conventions/). -* 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. -* Image file names use dashes (`-`) and suffix a build target, for example, `foreman`. -See also [Images](#Images). -* 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}_`. -* The first line of a file contains the modular docs content type attribute, for example, `:_mod-docs-content-type: ASSEMBLY` for assemblies. -The content type reflects the file prefix: `ASSEMBLY`, `PROCEDURE`, `CONCEPT`, or `REFERENCE`. -The only exceptions are `master.adoc` files, which do not require this attribute. - -### 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 | - -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_. -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. -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, e.g. tables with options. -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, e.g. admonitions. -Snippets do not require an ID. - -### Creating new guides +## Creating new guides Each guide must be in a separate directory in `guides/` prefixed with `doc-`. The following requirements must be met: From 0fc09a1733a331f34c35f209fd7d9e2bede4e8dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 19 Sep 2025 14:02:31 +0200 Subject: [PATCH 05/14] Add introductions to 2 readme files --- guides/README.md | 2 ++ web/README.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/guides/README.md b/guides/README.md index ba8313e0384..270ed110d81 100644 --- a/guides/README.md +++ b/guides/README.md @@ -1,5 +1,7 @@ # Foreman guides +This README file explains how to work with the guides included in this repository, including setting up your system for local testing. + This is upstream source code of [Red Hat Satellite 6](https://docs.redhat.com/en/documentation/red_hat_satellite/) documentation as well as parts of the [orcharhino documentation](https://docs.orcharhino.com/or/docs/index.html). This is **work in progress**, an attempt to take content written by Red Hat documentation team, modularize it, incorporate [Foreman Manuals](https://theforeman.org/manuals/), and eventually make this the only and official documentation for Foreman, Katello, and all plugins. diff --git a/web/README.md b/web/README.md index 66d105b51ca..6c3e822024a 100644 --- a/web/README.md +++ b/web/README.md @@ -1,5 +1,7 @@ # Foreman documentation site +This README explains how to work with the documentation website, including how to update the website and generate a local preview for testing. + Uses [nanoc](https://nanoc.app) site generator. Synopsis: From d340853ba70e8a51a63764c04b2692264d1ac4aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 19 Sep 2025 14:02:48 +0200 Subject: [PATCH 06/14] Remove guides/README intro It duplicates the general readme --- guides/README.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/guides/README.md b/guides/README.md index 270ed110d81..635708add30 100644 --- a/guides/README.md +++ b/guides/README.md @@ -2,13 +2,6 @@ This README file explains how to work with the guides included in this repository, including setting up your system for local testing. -This is upstream source code of [Red Hat Satellite 6](https://docs.redhat.com/en/documentation/red_hat_satellite/) documentation as well as parts of the [orcharhino documentation](https://docs.orcharhino.com/or/docs/index.html). - -This is **work in progress**, an attempt to take content written by Red Hat documentation team, modularize it, incorporate [Foreman Manuals](https://theforeman.org/manuals/), and eventually make this the only and official documentation for Foreman, Katello, and all plugins. - -Contributions are welcome. -Please read the [Contribution guidelines](#contribution-guidelines) before opening a Pull Request. - ## Building locally ### Installing tools From c6b61eea12d3864c0f0ef2420bc105f5c1f73651 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 19 Sep 2025 14:07:57 +0200 Subject: [PATCH 07/14] Add explanation about CP'ing --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29cb737b97b..32899183dd5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,6 +38,8 @@ 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. ## Foreman documentation minimalist style guide From 64161bce53d6a783f878a65e47ac26dfa4b34998 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 19 Sep 2025 14:12:11 +0200 Subject: [PATCH 08/14] Remove unmaintained RH resources --- CONTRIBUTING.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32899183dd5..0ebf57d4117 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,9 +45,6 @@ If unsure, I let reviewers know so that they can assist. ### Contribution guidelines -Please read these guidelines before opening a Pull Request. -For more information, see [Guidelines for Red Hat Documentation](https://redhat-documentation.github.io/). - 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/). If you are unsure into which guide you should place your content, have a look at the `docinfo.xml` files within each `doc-*` directory. @@ -57,7 +54,7 @@ If you are unsure into which guide you should place your content, have a look at Use the following markup conventions: * Source files use UTF-8 character encoding. -* Source files use [AsciiDoc](https://docs.asciidoctor.org/asciidoc/latest/) syntax and aim to follow [AsciiDoc Mark-up Conventions for Red Hat Documentation](https://redhat-documentation.github.io/asciidoc-markup-conventions/). +* 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. From 098c60fdb101ce14e6a347ef324c1b724013e50e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 19 Sep 2025 14:13:14 +0200 Subject: [PATCH 09/14] Remove obsolete advice --- CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0ebf57d4117..99bcd773ea6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,8 +47,6 @@ If unsure, I let reviewers know so that they can assist. 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/). -If you are unsure into which guide you should place your content, have a look at the `docinfo.xml` files within each `doc-*` directory. - ### Code conventions Use the following markup conventions: From 95d95f2501ee5daeaa38655b43bce710f6cd7d97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 19 Sep 2025 14:15:24 +0200 Subject: [PATCH 10/14] Drop and move redundant 'contributing guideliens' --- CONTRIBUTING.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99bcd773ea6..92f3fe56f67 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing to Foreman Documentation +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: @@ -43,10 +45,6 @@ If unsure, I let reviewers know so that they can assist. ## Foreman documentation minimalist style guide -### Contribution guidelines - -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/). - ### Code conventions Use the following markup conventions: From 9701f9b55528de53d0e73efb211328bcf42908a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 19 Sep 2025 14:17:56 +0200 Subject: [PATCH 11/14] Drop image naming guidelines that nobody seems to follow --- CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92f3fe56f67..500f7e4bf45 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,8 +56,6 @@ 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. -* Image file names use dashes (`-`) and suffix a build target, for example, `foreman`. -See also [Images](#Images). * 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}_`. * The first line of a file contains the modular docs content type attribute, for example, `:_mod-docs-content-type: ASSEMBLY` for assemblies. From 71ee601531a61d2a0812b5e286c9dbc322cb266e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 19 Sep 2025 14:20:47 +0200 Subject: [PATCH 12/14] Merge content type info with modular file info --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 500f7e4bf45..09195db294c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,9 +58,6 @@ This makes `git diff` much easier to read and helps when reviewing changes. 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}_`. -* The first line of a file contains the modular docs content type attribute, for example, `:_mod-docs-content-type: ASSEMBLY` for assemblies. -The content type reflects the file prefix: `ASSEMBLY`, `PROCEDURE`, `CONCEPT`, or `REFERENCE`. -The only exceptions are `master.adoc` files, which do not require this attribute. ### Images @@ -157,10 +154,13 @@ See the [assembly template](https://raw.githubusercontent.com/redhat-documentati 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, e.g. 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, e.g. admonitions. Snippets do not require an ID. From 093bb0cda53ff6e0dcc0ed5bf13754b0f1a1aded Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 19 Sep 2025 14:46:13 +0200 Subject: [PATCH 13/14] Move review checklist to PR checklist --- .github/PULL_REQUEST_TEMPLATE.md | 13 ------------- CONTRIBUTING.md | 13 +++++++++++++ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 05e23e83ac4..cf190e1447b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09195db294c..d2c6f141f3f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,6 +43,19 @@ See [Capitalization](#Capitalization). * [ ] 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 From 8d63fbcb0d06ff1f018ba016963bfa1807ef8654 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Mon, 22 Sep 2025 12:59:56 +0200 Subject: [PATCH 14/14] Apply easy fixes from style review Co-authored-by: Maximilian Kolb --- CONTRIBUTING.md | 12 ++++++------ README.md | 4 ++-- web/README.md | 3 ++- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d2c6f141f3f..8970460dbef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ Non-trivial PRs might not only benefit from additional review but they also repr * [ ] 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. @@ -94,9 +94,9 @@ Therefore, never write "Foreman", "Satellite", or "orcharhino" words directly, b | -------- | -------------- | --------------------- | ------------------ | | {Project} | Foreman | Satellite | orcharhino | | {ProjectName} | Foreman | Red Hat Satellite | orcharhino | -| {ProjectServer} | Foreman server | Satellite Server | orcharhino server | +| {ProjectServer} | Foreman server | Satellite Server | orcharhino Server | | {SmartProxy} | Smart Proxy | Capsule | orcharhino Proxy | -| {SmartProxyServer} | Smart Proxy server | Capsule Server | 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: @@ -172,11 +172,11 @@ See the [concept template](https://raw.githubusercontent.com/redhat-documentatio * [`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, e.g. tables with options. +* [`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, e.g. admonitions. -Snippets do not require an ID. +* [`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 diff --git a/README.md b/README.md index 930ce99a7ae..623a5d3cf36 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Foreman community welcomes all feedback, issues, pull requests (PRs), and review 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. +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. Familiarize yourself with [CONTRIBUTING](CONTRIBUTING.md) before you start contributing. @@ -64,7 +64,7 @@ When a commit is pushed into `X.Y`: ## Branching a new release -When a new Foreman version is released, the Foreman release owner ensures that a new branch for documentation is created. +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: diff --git a/web/README.md b/web/README.md index 6c3e822024a..f69faca0e5e 100644 --- a/web/README.md +++ b/web/README.md @@ -28,4 +28,5 @@ To edit the main menu, navigate to content/js/nav.js and edit the file, publish the changes and all guides and pages will dynamically load the menu from the data structure. -To test full site with guides, use the Makefile in the root directory. See [README](../README.md) for more information. +To test full site with guides, use the Makefile in the root directory. +See [README](../README.md) for more information.