Add style definition for abstracts #4315
Conversation
github-actions
bot
added
Needs tech review
aneta-petrova
removed
the
Needs tech review
|
Right now, the abstracts are shown only in these guides (all flavors): https://theforeman-foreman-documentation-preview-pr-4315.surge.sh/nightly/Managing_Configurations_Puppet/index-katello.html Because that's where the |
|
That's a nice thought! However, I think that the suggested style is a bit too much.
Let me know what you think. I'm trying to figure out an alternative style, but let's think it through first. |
Good point!
True.
Thanks for the review! I'm open to suggestions on alternative styles, this one was just a very quickly draft for an early proof-of-concept preview. |
|
I removed the extra space below the abstract paragraph because that was indeed jarring. First suggestion with light grey background (current preview): 
Second suggestion without the background: 
I actually prefer the first one with the background because I think the clearer visual separation actually helps users focus on the "fun" part of the module content. At the risk of overthinking this, just like the well-known Ebbinghaus illusion shows that human perception tends to focus on a smaller object, when looking at the preview, my brain at least tends to focus on the non-highlighted ("smaller") part of a give section. |
My brain focuses on the bar on the left of the abstract paragraph... The left border is too much. Makes it look like an admonition. |
|
This is without the border, just background: 
IMO too similar to a code block, not enough visual separation. That separation is needed because the point of an abstract is to be separated from the main text; you should be clear on where one ends and the other begins. For completeness, the other alternatives I tried were no background + borders on the left and right sides (that looked uneven because there was always more space on the right than on the left), no background + border on the bottom side (that was too distracting), and no background + borders all around (too much). My preference is still for the current version in the preview: border on one side, light background, not too much padding around. |
|
I looked for existing examples elsewhere and found something I liked on GH docs: https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github?platform=linux This uses larger font and a visually distinct color. I'm not sure about the larger font for our use case but I liked the more visually distinct color: 
For me, this meets the requirement for clear separation but there is no border. Would that work @Lennonka? |
|
About #4318: I tried a border on the bottom myself at one point (#4315 (comment)). To me, that's something that basically splits the section into two and personally I'm not a fan. EDIT: For completeness, I'm adding a screenshot too: 
|
Not bad. Is it the same color as headings? |
Not the main section headings but the lower-level headings like discrete headings ( |
|
I'd try the color of the main section headings. The abstract would visually blend with the heading, slightly shifting the focus. |
Sections with just the main heading look alright: 
However, when I look at sections that contain a discrete heading, I think the contrast is too much: 
|
|
You're right, it's too bright. Fair enough. Let's go with the color of discrete headings. That works well 👍 |
|
Thanks @Lennonka! This was a great brainstorming session! 🚀 Let's keep this open for additional reviews. I think that if there is at least one more ack, that should be good enough. If on the other hand there are further concerns or suggestions, we can keep working on this. |
What changes are you introducing?
Adding a CSS style definition for paragraphs annotated with [role=_abstract].
Why are you introducing these changes? (Explanation, links to references, issues, etc.)
In order to address the requirements for Red Hat's downstream DITA pre-migration checks (https://github.com/jhradilek/asciidoctor-dita-vale/), we are now required to add abstract metadata to introductory paragraphs (http://github.com/theforeman/foreman-documentation/pull/4221). I thought it might be nice to use this metadata to visually separate abstract paragraphs on the Foreman side.
EDIT: The comments below show several other alternatives that are being discussed.
IMO this sort of visual separation improves readability (users will immediately know which part of a module is an abstract and where the actual fun begins). But also, seeing the abstract highlighted like this in preview might help us all write abstract as summaries (authors and reviewers will immediately see that an abstract is something else than the rest of the introduction).
Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
For transparency: The CSS definition was generated by Gemini and I only made minor tweaks to it. (The prompt I used was to make the abstracts look similar to standard AsciiDoc [INFO] blocks.) Feel free to suggest different CSS attributes if you'd prefer something else.
EDIT: And what is actually an "abstract"? It's a single paragraph that explains the purpose or theme of the module. It serves as a confirmation that users are in the right place. https://github.com/jhradilek/asciidoctor-dita-vale/ will eventually include some additional rules for abstracts, such as that the required number of characters or allowed syntax.
Contributor checklists
Please cherry-pick my commits into: