Add a guidance for assembly titles - Issue #118 by mjahoda · Pull Request #192 · redhat-documentation/modular-docs (original) (raw)

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Conversation5 Commits4 Checks0 Files changed

Conversation

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters

[ Show hidden characters]({{ revealButtonHref }})

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mjahoda thanks for taking the initiative with this.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@emmurphy1 I'm sorry that it took so long.

To your suggestion: The fact that it can be also a noun phrase is new for me. This is another good argument for adding this definition to the guide :-). However, the second provided example use title case. Therefore, I will incorporate your suggestion manually. Thank you.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@emmurphy1 I did some research and I recalled the Write Better Titles and Headings course [1]. Ingrid's comment:

Assembly headings should be gerunds if the assemblies contain procedures. From the templates:
[id="assembly-my-user-story_{context}"]
= My user story
////
Be sure to include a line break between the title and the :context: variable and the :context: variable and the assembly introduction.

If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
////

...reminded me that we have the corresponding guidance in the templates already :-)

[1] https://360.articulate.com/review/content/1f7f2e1c-fceb-414b-83e1-59aff6a0eaf6/review

…adoc

Co-authored-by: emmurphy1 30830712+emmurphy1@users.noreply.github.com

2 participants