Clarify rules for text following [role="_abstract"] in the templates

redhat-documentation / modular-docs

Modular Documentation Project provides guidelines and examples for writing technical documentation using a modular framework.

Creative Commons Attribution Share Alike 4.0 International

80 stars 67 forks source link

Clarify rules for text following [role="_abstract"] in the templates #160

Closed stoobie closed 3 years ago

stoobie commented 3 years ago

Currently the templates say this:

Write a short introductory paragraph that provides an overview of the module. Procedure modules should include the steps that users perform and address user motivation.The text that immediately follows the[role="_abstract"]tag is used for search metadata. Please clarify what delineates an abstract paragraph.

Does the abstract need to be on a single line or can it span multiple lines?
Can a procedure abstract include bullets?
Also note need to add a space between "motivation." and "The"

emmurphy1 commented 3 years ago

https://github.com/redhat-documentation/modular-docs/pull/163

emmurphy1 commented 3 years ago

@stoobie , the board decided to keep PV2-specific information out of the templates as much as possible so we have provided minimal instructions about what should go in the short introductions. When you include this in the PV2 User Guide, please ask users to include key words that can be useful in a search. This is the main reason for the abstract tag as I understand it. We can work with you to help shape the content if you like. @adahms, I have merged the PR and am now closing this issue.