Add a guidance for assembly titles - Issue #118 #192
Conversation
| [discrete] | ||
| == Assembly title | ||
|
|
||
| The title of an assembly is a gerund phrase, such as *Encrypting block devices using LUKS*. |
There was a problem hiding this comment.
@mjahoda thanks for taking the initiative with this.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
@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 :-)
modular-docs-manual/content/topics/module_guidelines-assembly.adoc
Outdated
Show resolved
Hide resolved
…adoc Co-authored-by: emmurphy1 <[email protected]>
#118