Modularize Foreman API guide #3353

maximiliankolb · 2024-10-07T12:20:39Z

What changes are you introducing?

Modularize content in guides/common/modules related to the Foreman API guide
Unifying anchors: Is a original effort by Lena to bring the Foreman API guide upstream, we briefly discussed to way to set anchors. If I remember correctly, we though about using the api- prefix similar to the cli- prefix for CLI procedures. I consider this to have value on its own; and allow for a smoother transition in case we ever decide that we want to also show the API procedure as part of "normal aka. WebUI-based" workflows.
Using long options for commands (mostly curl) to provide better readability
Using one argument per line to also simplify readability

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

mostly to improve maintainability by splitting content into smaller modules. to align with existing content; help downstream integration; to prepare for the eventual merge with WebUI related procedures.

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Refs https://github.com/theforeman/foreman-documentation/pull/3212/files#r1746164481
I would like your opinion on "=" vs "." headings. If we have a consensus, I'd be happy to implement this as part of this PR.
Do we want to keep --request GET for curl commands? It's the default HTTP method and the command would also work without.
Do we want to use single or double quotes for quotes commands? I did not yet actively try to unify this but would if someone makes a proposal and is willing to review 😃

Checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.12/Katello 4.14 (Satellite 6.16)
Foreman 3.11/Katello 4.13
Foreman 3.10/Katello 4.12
Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
Foreman 3.8/Katello 4.10
Foreman 3.7/Katello 4.9 (Satellite 6.14)
Foreman 3.6/Katello 4.8
Foreman 3.5/Katello 4.7 (Satellite 6.13; orcharhino 6.6/6.7)
We do not accept PRs for Foreman older than 3.5.

github-actions · 2024-10-07T12:23:42Z

The PR preview for 40397d6 is available at theforeman-foreman-documentation-preview-pr-3353.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

guides/common/assembly_api-requests-in-various-languages.adoc

guides/common/modules/proc_applying-errata-to-hosts.adoc

guides/common/modules/proc_creating-and-modifying-resources.adoc

guides/common/modules/proc_passing-json-data-to-the-api-request.adoc

guides/common/modules/proc_retrieving-a-list-of-resources.adoc

guides/common/modules/proc_uploading-content-to-projectserver.adoc

guides/common/modules/proc_using-apipie-bindings-with-ruby.adoc

Lennonka · 2024-10-14T19:17:17Z

Do we want to keep --request GET for curl commands?

I'd suggest to keep it for clarity because some endpoints can be accessed by using multiple methods and it's more descriptive to be explicit about the method in use even if it's the default one.

Lennonka

My few cents.

guides/common/assembly_api-requests-in-various-languages.adoc

guides/common/modules/proc_applying-errata-to-hosts.adoc

guides/common/modules/proc_creating-and-modifying-resources.adoc

guides/common/modules/proc_creating-objects-by-using-python.adoc

guides/common/modules/proc_deleting-openscap-reports.adoc

Lennonka · 2024-10-14T19:58:16Z

Do we want to use single or double quotes for quotes commands?

I'm assuming you mean inside the Python and Ruby code. Assuming they won't change the functionality (if they are semantically same), we might go with " (double quotes) because it looks like they are used more frequently in the code and are better for readability.

However, this requires a more in-depth research as to the semantics of the code IMHO. Perhaps even developer review.

maximiliankolb

Rebased to "master" and started working on applying feedback. Draft for now!

guides/common/assembly_api-requests-in-various-languages.adoc

guides/common/modules/proc_applying-errata-to-hosts.adoc

guides/common/modules/proc_creating-and-modifying-resources.adoc

maximiliankolb

Implemented the suggestion to use ".API request" and ".API repsonse" in all applicable files.

As a follow-up task, we should look at all procedures relating to applying errata to hosts: there are quite a few! For now, I consider this out of scope.

guides/common/modules/proc_creating-objects-by-using-python.adoc

guides/common/modules/proc_applying-errata-to-hosts.adoc

guides/common/assembly_api-requests-in-various-languages.adoc

guides/common/modules/proc_returning-multiple-pages.adoc

guides/common/modules/proc_applying-errata-to-a-host-collection.adoc

guides/common/modules/con_api-request-composition.adoc

guides/common/modules/con_working-with-lifecycle-environments.adoc

maximiliankolb · 2024-11-07T06:31:05Z

Rebased to "master", resolved a merge conflict, and reverted a change "MB -> MiB".

guides/common/modules/proc_uploading-content-to-projectserver.adoc

Lennonka

One last suggestion. The rest looks good!

guides/common/modules/ref_json-response-metadata.adoc

guides/common/modules/con_calling-the-api-in-curl.adoc

guides/common/modules/proc_creating-linked-lifecycle-environments.adoc

guides/common/modules/proc_creating-objects-by-using-ruby.adoc

guides/common/modules/proc_deleting-a-lifecycle-environment.adoc

guides/common/modules/proc_updating-a-lifecycle-environment.adoc

guides/common/modules/proc_uploading-content-larger-than-2-mb.adoc

maximiliankolb

Rebased to "master" and applied all feedback by @bangelic and @Lennonka

Thanks for the review, ready for re-review.

guides/common/modules/proc_uploading-content-to-projectserver.adoc

guides/common/modules/con_calling-the-api-in-curl.adoc

guides/common/modules/proc_creating-linked-lifecycle-environments.adoc

guides/common/modules/proc_deleting-a-lifecycle-environment.adoc

guides/common/modules/proc_updating-a-lifecycle-environment.adoc

guides/common/modules/proc_uploading-content-larger-than-2-mb.adoc

guides/common/modules/ref_json-response-metadata.adoc

apinnick · 2024-11-11T11:54:01Z

guides/common/modules/proc_applying-errata-to-hosts.adoc

+. In the {ProjectWebUI}, navigate to *Hosts* > *Host Collections*.
+. Select a host collection.
+. On the *Actions* tab, click *Errata Installation*.
+. Follow the {ProjectWebUI} to install errata.


"Follow the UI to install errata" is pretty vague for a procedure step.

If your PR covers only modularization, then my comment is probably outside the scope of this task. Do you think this justifies a bug?

I believe that we've started to remove doc bloat if the WebUI is good and the user is guided by a wizard. This is one of these instances.

This is a slippery slope. I want to discuss this with you offline.

Can you please continue the conversation here (rather than offline)? I'm actually following this thread and am interested in the topic. (I agree with Max that if the steps are explained in the wizard/UI, duplicating them in the docs is not the best idea.)

@maximiliankolb I checked the wizard in the web UI and yes, it works just fine on its own. Perhaps you could add its name, to help users check they landed on the right page in case of any confusion? How about something like this:

Suggested change

. Follow the {ProjectWebUI} to install errata.

. Follow the *Content Host Errata Management* wizard in the {ProjectWebUI} to install errata.

Looking into the IBM style guide, it does include this in one of its examples:

[Step 1]

In the wizard, follow the instructions on each page.

[Step 3]

So it doesn't look like we're breaking any official convention with this approach.

If the "installing errata" wizard is extremely brief, that might be a consideration.

Re: my own reservations. This is something that I would prefer to discuss with our team.

I'd rather not share a direct link to a closed resource. A full-text search of the pdf should get you where you need to be but just in case it doesn't: the example is in Punctuation > Colons > Introductory text. While I realize that this section is not centered around describing UI elements, I don't think it matters because the example is still there 🤷 Also, I didn't see anything that would discourage from this approach in Technical elements > UI elements > Usage and highlighting for interface elements (where wizards are actually described).

I'm not totally opposed to deviating from a style guide in cases when there is a reason. I didn't mean my comments to be a conversation stopper. As I mentioned, I looked at the wizard itself and reached the conclusion that no additional documentation support was necessary + I checked the style guide to make sure it supports this approach. If you disagree, I'd be happy to hear why :)

Oh well, I took too long to write up my comment :) That's what happens when I try too hard.

To quote your example:

In the “Printer setup” wizard, specify details about the printer that you want to use.

vs this PR's

Follow the Content Host Errata Management wizard in the {ProjectWebUI} to install errata.

is basically the same thing: Printer setup wizard/Content Host Errata Management wizard > specify printer details/install errata. In my opinion, it all comes down to actually trying the wizard and seeing what it looks like.

It's interesting that this wizard is not documented anywhere. I was only able to find the CLI procedure for applying errata to a host collection. I checked the host management guide as well.

apinnick · 2024-11-13T09:08:59Z

guides/common/modules/proc_applying-errata-to-hosts.adoc

+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Hosts* > *Host Collections*.
+. Select a host collection.


Suggested change

. Select a host collection.

. Click a host collection to view the *Details* tab.

If the docs say "Select" whenever the user clicks to view details, you can ignore this comment for the sake of consistency.

apinnick · 2024-11-13T09:13:39Z

guides/common/modules/proc_applying-errata-to-hosts.adoc

+. In the {ProjectWebUI}, navigate to *Hosts* > *Host Collections*.
+. Select a host collection.
+. On the *Actions* tab, click *Errata Installation*.
+. Follow the {ProjectWebUI} to install errata.


Suggested change

. Follow the {ProjectWebUI} to install errata.

. On the *Content Host Errata Management* page, select the hosts and click *Done*.

I think a wizard has to have one or more pages.

guides/common/modules/proc_applying-errata-to-hosts.adoc

* Modularize content in "guides/common/modules" related to the Foreman API guide * Unifying anchors Is a original effort by Lena to bring the Foreman API guide upstream, we briefly discussed to way to set anchors. If I remember correctly, we though about using the api- prefix similar to the cli- prefix for CLI procedures. I consider this to have value on its own; and allow for a smoother transition in case we ever decide that we want to also show the API procedure as part of "normal aka. WebUI-based" workflows. * Using long options for commands (mostly curl) to provide better readability * Using one argument per line to also simplify readability

maximiliankolb

Rebased to "master" and reworded one procedure. This PR is only about modularizing existing content. Kindly asking for re-review @apinnick and @asteflova

I would be happy to do a quick follow-up PR to reword the Web UI wizard.

guides/common/modules/proc_applying-errata-to-hosts.adoc

maximiliankolb · 2024-11-13T14:24:11Z

Merged to "master" and cherry-picked to "3.13":
17f6cb7..d657a19 3.13 -> 3.13

Thanks to everyone for their input. @apinnick @Lennonka @asteflova If you want to propose any follow-up changes, esp. to procedures about "applying errata" (we have a lot of these!), ping me. I could also open an upstream issue and look into this myself soon.

pr-processor bot added the Not yet reviewed label Oct 7, 2024

maximiliankolb force-pushed the api_anchors branch 3 times, most recently from 3c1af6c to 305f215 Compare October 10, 2024 11:11

maximiliankolb commented Oct 10, 2024

View reviewed changes

pr-processor bot removed the Not yet reviewed label Oct 10, 2024

maximiliankolb force-pushed the api_anchors branch from 305f215 to a358a3a Compare October 10, 2024 12:27

maximiliankolb marked this pull request as ready for review October 10, 2024 12:39

maximiliankolb force-pushed the api_anchors branch from a358a3a to 3cafdbe Compare October 11, 2024 05:15

Lennonka reviewed Oct 14, 2024

View reviewed changes

maximiliankolb added tech review done No issues from the technical perspective Needs style review Requires a review from docs style/grammar perspective labels Oct 15, 2024

maximiliankolb force-pushed the api_anchors branch from f16f584 to 6b74008 Compare October 17, 2024 10:21

maximiliankolb commented Oct 17, 2024

View reviewed changes

guides/common/assembly_api-requests-in-various-languages.adoc Outdated Show resolved Hide resolved

guides/common/modules/proc_applying-errata-to-hosts.adoc Outdated Show resolved Hide resolved

guides/common/modules/proc_creating-and-modifying-resources.adoc Outdated Show resolved Hide resolved

maximiliankolb marked this pull request as draft October 17, 2024 10:22

maximiliankolb mentioned this pull request Oct 17, 2024

Rephrase comments in example Python/Ruby/Shell scripts #3379

Open

maximiliankolb force-pushed the api_anchors branch from 6b74008 to 13dc9d2 Compare October 17, 2024 11:28

maximiliankolb commented Oct 17, 2024

View reviewed changes

guides/common/modules/proc_creating-objects-by-using-python.adoc Show resolved Hide resolved

guides/common/modules/proc_applying-errata-to-hosts.adoc Outdated Show resolved Hide resolved

guides/common/assembly_api-requests-in-various-languages.adoc Show resolved Hide resolved

maximiliankolb marked this pull request as ready for review October 17, 2024 11:32

maximiliankolb force-pushed the api_anchors branch from 13dc9d2 to 548bd26 Compare October 17, 2024 11:35

maximiliankolb commented Oct 17, 2024

View reviewed changes

guides/common/modules/proc_returning-multiple-pages.adoc Show resolved Hide resolved

maximiliankolb requested a review from Lennonka October 17, 2024 11:38

maximiliankolb force-pushed the api_anchors branch from 548bd26 to 3ad3153 Compare October 18, 2024 06:39

maximiliankolb commented Oct 18, 2024

View reviewed changes

guides/common/modules/proc_applying-errata-to-a-host-collection.adoc Show resolved Hide resolved

Lennonka requested changes Oct 30, 2024

View reviewed changes

guides/common/modules/con_api-request-composition.adoc Outdated Show resolved Hide resolved

guides/common/modules/con_working-with-lifecycle-environments.adoc Outdated Show resolved Hide resolved

pr-processor bot added the Waiting on contributor Requires an action from the author label Oct 30, 2024

maximiliankolb force-pushed the api_anchors branch from 3ad3153 to fd84b61 Compare October 31, 2024 09:57

pr-processor bot added Needs re-review and removed Waiting on contributor Requires an action from the author Needs re-review labels Nov 7, 2024

Lennonka reviewed Nov 7, 2024

View reviewed changes

guides/common/modules/proc_uploading-content-to-projectserver.adoc Outdated Show resolved Hide resolved

Lennonka approved these changes Nov 7, 2024

View reviewed changes

guides/common/modules/ref_json-response-metadata.adoc Outdated Show resolved Hide resolved

bangelic suggested changes Nov 7, 2024

View reviewed changes

pr-processor bot added the Waiting on contributor Requires an action from the author label Nov 7, 2024

maximiliankolb force-pushed the api_anchors branch from 6da393f to dcdf8e6 Compare November 8, 2024 08:00

pr-processor bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Nov 8, 2024

maximiliankolb commented Nov 8, 2024

View reviewed changes

pr-processor bot removed the Needs re-review label Nov 8, 2024

apinnick reviewed Nov 11, 2024

View reviewed changes

apinnick reviewed Nov 13, 2024

View reviewed changes

guides/common/modules/proc_applying-errata-to-hosts.adoc Show resolved Hide resolved

maximiliankolb added 5 commits November 13, 2024 13:44

Introduce API request and API response titles

2118d0d

Hide Web and CLI procedures in API guide

8654bb2

Use description list in favor of dashes

7bcf124

Reword applying errata to hosts

40397d6

maximiliankolb force-pushed the api_anchors branch from dcdf8e6 to 40397d6 Compare November 13, 2024 12:51

maximiliankolb commented Nov 13, 2024

View reviewed changes

guides/common/modules/proc_applying-errata-to-hosts.adoc Show resolved Hide resolved

asteflova approved these changes Nov 13, 2024

View reviewed changes

maximiliankolb added style review done No issues from docs style/grammar perspective and removed Needs style review Requires a review from docs style/grammar perspective labels Nov 13, 2024

maximiliankolb merged commit ab42408 into theforeman:master Nov 13, 2024
9 checks passed

maximiliankolb deleted the api_anchors branch November 13, 2024 14:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Modularize Foreman API guide #3353

Modularize Foreman API guide #3353

maximiliankolb commented Oct 7, 2024 •

edited

Loading

github-actions bot commented Oct 7, 2024 •

edited

Loading

Lennonka commented Oct 14, 2024 •

edited

Loading

Lennonka left a comment

Lennonka commented Oct 14, 2024

maximiliankolb left a comment

maximiliankolb left a comment

maximiliankolb commented Nov 7, 2024

Lennonka left a comment

maximiliankolb left a comment

apinnick Nov 11, 2024

maximiliankolb Nov 11, 2024

apinnick Nov 12, 2024

asteflova Nov 12, 2024

asteflova Nov 12, 2024

apinnick Nov 12, 2024

apinnick Nov 12, 2024

asteflova Nov 12, 2024

asteflova Nov 12, 2024

apinnick Nov 13, 2024

apinnick Nov 13, 2024

apinnick Nov 13, 2024

maximiliankolb left a comment

maximiliankolb commented Nov 13, 2024

	. Follow the {ProjectWebUI} to install errata.
	. Follow the Content Host Errata Management wizard in the {ProjectWebUI} to install errata.

	. Select a host collection.
	. Click a host collection to view the Details tab.

	. Follow the {ProjectWebUI} to install errata.
	. On the Content Host Errata Management page, select the hosts and click Done.

Modularize Foreman API guide #3353

Modularize Foreman API guide #3353

Conversation

maximiliankolb commented Oct 7, 2024 • edited Loading

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Checklists

github-actions bot commented Oct 7, 2024 • edited Loading

Lennonka commented Oct 14, 2024 • edited Loading

Lennonka left a comment

Choose a reason for hiding this comment

Lennonka commented Oct 14, 2024

maximiliankolb left a comment

Choose a reason for hiding this comment

maximiliankolb left a comment

Choose a reason for hiding this comment

maximiliankolb commented Nov 7, 2024

Lennonka left a comment

Choose a reason for hiding this comment

maximiliankolb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

maximiliankolb left a comment

Choose a reason for hiding this comment

maximiliankolb commented Nov 13, 2024

maximiliankolb commented Oct 7, 2024 •

edited

Loading

github-actions bot commented Oct 7, 2024 •

edited

Loading

Lennonka commented Oct 14, 2024 •

edited

Loading