Content feedback:

[Marius-ASAM]

Prerequisites

This is in regards to:

• [ ] Title
• [x] Content: Text
• [ ] Content: Image(s)
• [ ] Formatting
• [ ] Location in Project Guide
• [ ] Obsolete

Subject

Capitalization

Section

Figure 1

Description

The capitalization of the Figure's description seems odd

Suggestion

Please define and apply across the whole document consistent rules for capitalization. If "Proposal Phase" is a single term, then write "The Proposal Phase timeline" in the figure caption. If not, the figure caption should read "The proposal phase timeline"

URL	https://asam-ev.github.io/asam-project-guide/asamprojectguide/latest/getting-involved/proposal_phase.html
Page	Proposal Phase
Module	getting-involved

[philipwindecker]

The Editorial Guide is currently being developed in a fork. This fork is supposed to be merged in the near future and it contains all currently valid or discussed sets of rules for writing and editing content in standards. I would like to apply those rules (or at least an agreed subset of them) to the Project Guide as well once the Editorial Guide is ready. Until then, I would suggest we leave this issue open.

[philipwindecker]

P.S.: There already is an older version of the Editorial Guide in the Compendium, but it is very much not up-to-date and, therefore, I would refrain from applying its rules just now.

[christiangoedert]

Just the first character of headings and captions is capitalized.

A rule for headings exists: 5.3. Start headings with a capital letter (ASM-2)

The rule for captions contains an example but does currently not define how to apply upper and lower case writing specifically to captions: 10.8. Create a caption for every figure (ASM-58)

[Marius-ASAM]

The rule for captions is ok. But if "Proposal Phase" is a specific term, then it must also appear with upper case initial letters in a caption. You also wouldn't write your own name lowercase just because it appears in the middle of a caption text. And I would highly recommend that rules that are already known at this moment be applied across all text at the moment of its creation. Reviewing the whole document afterwards for the correct application of the rules is quite a lot of work.

[christiangoedert]

You are right. Proper names should be written as they are. Is "Proposal Phase" a proper name?

[Marius-ASAM]

This is exactly part of my original question. And I'm adding: who will define the proper names?

[philipwindecker]

I have updated the guide since my comment, so most section titles should now follow these rules (only "most" since my RegEx may not have captured every variant correctly).

I agree that a definition is required for terms that may or may not be considered proper names. This, in particular, covers

• phase names (e.g. Proposal Phase, proposal phase, or Proposal phase?)
• phase steps and events (e.g. Proposal Workshop, proposal workshop, or Proposal workshop?)
• roles (e.g. Project Lead or project lead?)

My suggestion:

• Phase names start with capital letters, but only the name (not phase): Proposal phase, Development phase, etc. This highlights the name and separates its meaning from the "phase" part
• Workshops and events that are unique and well-defined (such as TSC meetings) use Title Case: Proposal Workshop, Kick-off Workshop
• Non-specific meeting types only capitalize words that are to be capitalized due to other rules: CCB meeting
• Roles used and described in the Project Guide are Title Case, if they are no abbreviations: Project Lead, Idea Giver
• Abbreviations in roles are all-caps: GTM, TSC

Reasons: In my eyes, this elevates these terms and makes them easier to identify on each page and in graphics. When reading, it should make it easier to quickly scan the page to see if it targets me (my role) or a specific event I am looking for.

[Marius-ASAM]

The rules look good to me. Who will now decide whether we make them mandatory? (sorry for asking stupid questions)

[philipwindecker]

I do not think this is a stupid question! I would suggest to discuss this shortly in tomorrows Daily and either schedule a short meeting or have the discussion here.