Add [role] element to introductions in user auth, puppet, and lb #4221
Conversation
github-actions
bot
added
Needs tech review
aneta-petrova
removed
Needs tech review
|
Good to see the role being added. We will also need to review these paragraphs to ensure that they follow RHSSG guidelines for short descriptions. |
There was a problem hiding this comment.
Per Tomas Capek's RHEL docs plan, we need to review the "abstract" sections to ensure that they comply with 'short description' guidelines for DITA migration.
A lead-in sentence followed by a bullet list, for example, cannot be converted to a DITA short description.
pr-processor
bot
added
Waiting on contributor
|
Thanks for the feedback, Avital! You're right that there will be more work required around short descriptions down the line. I created https://issues.redhat.com/browse/SAT-38120 to track this. In the meantime, I decided to scale back this PR and focus solely on the core goal, which is to ensure a clean asciidoctor-dita-vale report per the specification in https://issues.redhat.com/browse/SAT-36254, https://issues.redhat.com/browse/SAT-36301, and https://issues.redhat.com/browse/SAT-36305. |
|
@maximiliankolb Can you please take a look here? Adding the [role] element won't break anything for you, will it? |
|
The direction from downstream says not to add [role] unless the associated descriptions can be reviewed. Closing for now. |
|
@aneta-petrova Should I check downstream if this works for me? |
Yes, please :) We just have a couple of things to figure out on our side first but then I (or someone else) will be back with this change. |
|
Yes, this change would work for me in downstream. |
Although both RHEL and Foreman documentation teams are aligning with downstream DITA migration requirements, RHEL documentation plans do not directly affect Foreman documentation upstream. The purpose of this PR is to contribute to resolving issues reported by the Vale asciidoctor-dita-vale rule set (https://github.com/jhradilek/asciidoctor-dita-vale). We are tracking this effort in https://github.com/theforeman/foreman-documentation/milestone/8, having secured an agreement with the upstream documentation team about the effort in the past few months. To move this PR, and by extension https://github.com/theforeman/foreman-documentation/milestone/8, forward, I will reopen this PR and continue adding the [role="_abstract"] asciidoc element on these grounds:
I will extend the PR a little bit to account for introductory paragraphs (also called "abstracts" now) that would not be complete sentences or that do not end with a complete sentence. I'm also using this PR to communicate with the asciidoctor-dita-vale's developer to make sure Foreman's needs are met in a way that complies with the DITA migration plan. Subsequent PRs can then focus on improving the abstracts further, which will allow for a separate, focused upstream discussion on the matter. |
|
Switching to draft while I resolve how to best address our "prerequisites" and "next steps" modules. |
aneta-petrova
removed
the
Needs style review
aneta-petrova
force-pushed
the
role-auth-puppet-security
branch
from
b93a2ed to
60fa1d5
Compare
aneta-petrova
force-pushed
the
role-auth-puppet-security
branch
from
60fa1d5 to
8ca6bc8
Compare
|
I updated the PR's description with a new summary of changes and also the purpose of this PR. With this PR, the goal is to ensure that the guides pass the asciidoctor-dita-vale check and that the paragraphs annotated by the abstract role are not incomplete (for example, that they don't end with a colon introducing a list). I'm not trying to make all abstracts perfect because that is planned for another time, another initiative, perhaps even another writer. Whoever works on reviewing the abstracts in the future should be the one to decide what an abstract needs to meet the (still not entirely defined) requirements. |
...common/modules/snip_preparing-smartproxyservers-for-load-balancing-additional-resources.adoc
Outdated
Show resolved
Hide resolved
...common/modules/snip_preparing-smartproxyservers-for-load-balancing-additional-resources.adoc
Outdated
Show resolved
Hide resolved
pr-processor
bot
added
the
Waiting on contributor
Co-authored-by: Maximilian Kolb <[email protected]>
pr-processor
bot
added
Needs re-review
and removed
Waiting on contributor
There was a problem hiding this comment.
I did my best to incorporate the results of our conversations @maximiliankolb. Can you please check?
...common/modules/snip_preparing-smartproxyservers-for-load-balancing-additional-resources.adoc
Outdated
Show resolved
Hide resolved
...common/modules/snip_preparing-smartproxyservers-for-load-balancing-additional-resources.adoc
Outdated
Show resolved
Hide resolved
* Add [role] to introductions in User Auth, Puppet, LB guides * Add missing introductions * Update intros that would be incomplete abstracts * Remove files in LB unsuitable for an abstract --------- Co-authored-by: Maximilian Kolb <[email protected]> (cherry picked from commit c268d27)
What changes are you introducing?
Why are you introducing these changes? (Explanation, links to references, issues, etc.)
The goal is to annotate the first paragraph of any module as an "abstract", which is supposed to be a short introduction summarizing the contents of the module. (jhradilek/asciidoctor-dita-vale#110 (comment))
The goal is not to ensure all abstracts are perfect. Only that the content is migrateable.
Follow up on #4189, #4178, and #4175.
Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
I used this to extract the modules for each of the guides and this to add the element:
The paragraphs annotated as "abstract" don't need to be perfect abstracts at this point. That's planned for later.
Contributor checklists
Please cherry-pick my commits into:
Review checklists
Tech review (performed by an Engineer who did not author the PR; can be skipped if tech review is unnecessary):
Style review (by a Technical Writer who did not author the PR):