Add guidance for writing abstracts

[rolfedh]

The templates include abstracts, but the reference guide doesn't mention them.

[stoobie]

@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]

@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]

@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]

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]

@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]

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]

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.

On Tue, Dec 7, 2021 at 7:45 PM Rolfe Dlugy-Hegwer @.***> wrote:

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.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/redhat-documentation/modular-docs/issues/170#issuecomment-988140812, or unsubscribe https://github.com/notifications/unsubscribe-auth/AJLVVLNAOO4EAAHGXUGVYALUPZB5DANCNFSM5DVAVMCA . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

--

Steve Goodman

Senior Technical Writer

Red Hat https://www.redhat.com

@.*** M: +972-54-430-1982 F: +972-9-769-2224 IM: sgoodman https://www.redhat.com

[rolfedh]

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]

@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]

@stoobie when the Pantheon 2/Jupiter user guide is published, we can added a link or links to the Modular Documentation Reference guide.

[stoobie]

@emmurphy1 Sorry I didn't notice this comment until now. The Pv2 User Guide has been published since around June of 2021. https://pantheon.corp.redhat.com/pantheon/docs/assemblies/assembly-pantheon-help.html

[emmurphy1]

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]

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]

This information is covered in the "procedure introduction", for example: https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs and in the SSG.

[bergerhoffer]

Also noting that the supplementary style guide added guidance on writing short descriptions (abstracts) here: https://redhat-documentation.github.io/supplementary-style-guide/#shortdesc

[bergerhoffer]

Sorry, didn't see your comment above in time @rolfedh :)