Make Updating guide ready for DITA migration

[AkshayGadhaveRH]

Making the changes resulting from the DITA vale tests results in the JIRA: https://issues.redhat.com/browse/SAT-36307

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.)

Contributor 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.16/Katello 4.18 (Satellite 6.18)
• Foreman 3.15/Katello 4.17
• Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4)
• Foreman 3.13/Katello 4.15 (EL9 only)
• Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
• Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9; orcharhino 7.1 with Leapp)
• 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.

[AkshayGadhaveRH]

Working on changing the discrete headings.

[github-actions]

The PR preview for f68d5cf is available at theforeman-foreman-documentation-preview-pr-4314.surge.sh

The following output files are affected by this PR:

• Updating_Project/index-foreman-deb.html
• Updating_Project/index-foreman-el.html
• Updating_Project/index-katello.html
• Updating_Project/index-orcharhino.html
• Updating_Project/index-satellite.html

show diff

show diff as HTML

[aneta-petrova]

Per discussion on today's standup, I reviewed this PR. So far so good :) There is still some work remaining to resolve all the issues reported by asciidoctor-dita-vale messages (like the discrete headings mentioned in one of the previous comments) but this already brings us nice few steps closer to making the guide ready for migration!

[aneta-petrova]

Hi @AkshayGadhaveRH, just to check the expectations and next steps because as a reviewer, I'm not sure about them: I'm still seeing a few issues when running an asciidoctor-dita-vale check. So just a question: Are you running your own checks and thus are aware of the remaining issues? Or are you working with the report that's part of the Jira ticket? (Because the Vale reports that were originally uploaded to Jira are no longer up-to-date and we should run our own checks.)

[aneta-petrova]

Hi Akshay, thanks for working on resolving the issues! I tried running asciidoctor-dita-vale on your PR and I get these three additional warnings. Are they on your radar?

 guides/common/modules/con_updating-project.adoc
 1:1  warning  Assign [role="_abstract"]       AsciiDocDITA.ShortDescription 
               to a paragraph to use it as                                   
               <shortdesc> in DITA.           
               
                guides/common/modules/proc_updating-foreman-server.adoc
 1:1  warning  Assign [role="_abstract"]       AsciiDocDITA.ShortDescription 
               to a paragraph to use it as                                   
               <shortdesc> in DITA.                                   
               
               guides/common/modules/proc_updating-smart-proxy-server.adoc
 1:1  warning  Assign [role="_abstract"]       AsciiDocDITA.ShortDescription 
               to a paragraph to use it as                                   
               <shortdesc> in DITA.                

[Lennonka]

Please, rebase your PR to get a clean build.

Also, we need these changes in Sat 6.18 as well -> I'm updating the cherry picks in description.

[maximiliankolb]

Suggested change

	[id="preparing-repos-for-export_{context}"]
	[id="preparing-the-repositories-for-export"]

Please also adjust the file name.