GeezerVison is showing github.com — Add guidance for writing abstracts · Issue #170 · redhat-documentation/modular-docs
Add guidance for writing abstracts #170DescriptionThe templates include abstracts, but the reference guide doesn't mention them. Activitystoobie commented on Oct 27, 2021 @redhat-documentation/ccs-style-council Please see this issue for adding guidance on writing abstracts.
@rolfedh The mod docs guide discusses introductions (short descriptions, i.e. abstracts) for modules of each content type.
There were several requests in today's style council meeting for examples.
@emmurphy1 Do you have any examples of abstracts? Is that something that could be added? bergerhoffer commented on Oct 27, 2021 @emmurphy1 Another request was for tips on how to make a good intro sentence when the heading is descriptive enough in itself (and we don't want the writer to repeat the exact same thing in the intro sentence). Tips for how else they can add value with that intro in this situation. rolfedh commented on Oct 28, 2021 ContributorAuthor More actions
@rolfedh The mod docs guide discusses introductions (short descriptions, i.e. abstracts) for modules of each content type.
@stoobie @bergerhoffer @emmurphy1
Various paradigms in technical communications, such as DITA, treat introductions, short descriptions, and abstracts as related but different things. Although we are not "a DITA shop," many writers have used DITA and might use it as the basis for understanding parameter names or elements in our templates. It would be very helpful for us to be clear about what these terms mean in the context of Modular Documentation.
More generally, as a technical writer at Red Hat, if an element appears in the templates, I'd like to be able to open the mod docs guide, and use ctrl+f to find an explanation of that element in the guide. rolfedh commented on Oct 28, 2021 ContributorAuthor More actions I seem to recall a presentation (don't remember who gave it) that said our future publishing tool would use abstracts as the blurbs below links in search results. For example:
 emmurphy1 commented on Dec 7, 2021 @rolfedh the tag 'abstract' is applied to what is functionally a DITA short description. I can see how that might be confusing. But I think there is some question about whether the abstract tag will be required by Jupiter. @bergerhoffer that is a great suggestion. Writing short descriptions is an art in itself and I think warrants a class or self-paced workshop. I'm not sure we should add much more to the instructions in the templates. Maybe others disagree or have ideas? rolfedh commented on Dec 7, 2021 ContributorAuthor More actions I'm concerned that we might be losing sight of an important user story:
"As a writer using the mod docs templates, I must be able to use the Modular Documentation Reference Guide as a reference for the mod docs templates. I must be able to search the guide for any element I encounter in the templates and find an example and explanation of how to use it. "
In this particular case, while [role="_abstract"] appears in our templates, the guide should provide an example and explanation of how to use it. We should also check to see if any other elements have been omitted. stoobie commented on Dec 8, 2021 The Pantheon 2 User's Guide now provides (or will provide upon the next
incremental update release of Pv2) this guidance.
You can see the module that describes this here:
https://github.com/redhataccess/pantheon/blob/master/pantheon-bundle/src/main/resources/SLING-INF/content/docs/modules/con_role-of-abstract.adoc
As I recall, we agreed that although the template owner was asked to
include some Pv2-implementation-specific tags, such as role="_abstract",
the documentation for such tags would be taken care of in the Pv2 User's
Guide. It might be worth adding a link to this topic. What's tricky,
though, is that the Mod Docs Guide is available to the world, while the
implemented instance of Pv2 (and its published User Guide) is only
available within Red Hat. rolfedh commented on Dec 9, 2021 ContributorAuthor More actions
The Pantheon 2 User's Guide now provides (or will provide upon the next incremental update release of Pv2) this guidance.
How might we help users of the mod docs templates and guide find information about Pv2-implementation-specific tags, such as role="_abstract"?
Who is the template owner? stoobie commented on Dec 9, 2021 @rolfedh @emmurphy1 I don't know how to answer that question. The easiest answer is to include either a link to the Pv2 User's Guide, or at least a textual reference. But the problem with that is that non-Red Hat users of the Guide won't have access to that info. I think that this problem is more philosophical than practical, unless there are a lot of non-Red Hat users. But even so you can solve this "problem" by adding a note indicating that although this guide is for the most part not tied to any specific implementation or publishing tool, there is some info that is specific to Red Hat. Then label that info where it appears. That's what I would do. emmurphy1 commented on Feb 7, 2022 @stoobie when the Pantheon 2/Jupiter user guide is published, we can added a link or links to the Modular Documentation Reference guide. stoobie commented on Mar 1, 2022 emmurphy1 commented on May 16, 2022 In a separate meeting, @IngridT1 and Lorena Abarca expressed interest in developing a training course for brief introductions (abstracts) under the minimalism umbrella and I volunteered to help. mjahoda commented on Sep 13, 2023
In this particular case, while [role="_abstract"] appears in our templates, the guide should provide an example and explanation of how to use it. We should also check to see if any other elements have been omitted.
Because the templates no longer contain the [role="_abstract"] declaration, I believe we can close this issue. rolfedh commented on Sep 13, 2023 ContributorAuthor More actions bergerhoffer commented on Sep 13, 2023 Reacted by Rolfe Dlugy-Hegwer bergerhoffer commented on Sep 13, 2023 Sorry, didn't see your comment above in time @rolfedh :) Reacted by Rolfe Dlugy-Hegwer
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|
