Discuss "Good, because" vs. "Pros:"

[koppor]

See https://github.com/microsoft/semantic-kernel/blob/main/docs/decisions/0007-support-multiple-named-args-in-template-function-calls.md for some real world usage.

Fuchsia also used "Pro:" and "Con:"

C++
Analysis
	• Pro: Many of our current end-developers use C++ extensively.
	• Pro: The Fuchsia Platform Source Tree uses C++ extensively.
	• Pro: C++ is a widely used language. The language has properties that are well-understood, have been stable over a long period of time, and have been used to build similar systems in the past. The language has a mature toolchain and associated developer tools.
	• Con: Support for asynchronous programming is weak.
	• Con: Programs written in the language often have security bugs arising from the language's lack of memory safety.
Decision
	• C++ is supported for end-developers. (See [the list of supported versions of C++](http://web.archive.org/web/20200523050317/https:/fuchsia.googlesource.com/fuchsia/+/refs/heads/master/docs/concepts/api/c.md#Language-versions).)
	• C++ is approved for use throughout the Fuchsia Platform Source Tree.

Source: http://web.archive.org/web/20200523050317/https:/fuchsia.googlesource.com/fuchsia/+/refs/heads/master/docs/project/policy/programming_languages.md#Go

[koppor]

I also like Unicode. On Windows with Win+., one can have a list of Emojis

Thus, why not

• 👍: Pro argument
• 🫤: Neutral argument
• 👎: Con argument

[koppor]

Maybe we should offer two variants? 😨

[koppor]

ChatGPT without any instructions lists Pros and cons as single bullet point

Q: YAML: field names: camel case? snake case? dash case? e.g., I want to have "decision-makers"
A:

When deciding on the case style for YAML field names, it's important to consider consistency, readability, and any specific conventions or standards that might be relevant to your project or industry. Here are the three options you mentioned, with a recommendation for each:

1. Camel Case (e.g., decisionMakers):

   • Pros: Commonly used in many programming languages (JavaScript, Java, etc.). Easy to read for those familiar with these conventions.
   • Cons: Can be less readable for long field names.
   • Example: decisionMakers

2. Snake Case (e.g., decision_makers):

   • Pros: Very readable, especially for long field names. Common in Python and many configuration files.
   • Cons: Can be less familiar to those from non-Pythonic backgrounds.
   • Example: decision_makers

3. Dash Case (e.g., decision-makers):

   • Pros: Very readable, looks clean, and is often used in YAML, especially in contexts like configuration files and APIs.
   • Cons: Some programming languages and parsers might have issues with dashes in field names.
   • Example: decision-makers

Recommendation

If you want to have a field name like "decision-makers," and your YAML will be used primarily for configuration files, APIs, or other contexts where readability is paramount and dash case is commonly accepted, then dash case is a good choice.

However, if your YAML will interact closely with programming languages that prefer camel case or snake case, it might be better to align with those conventions.

Here is how you might structure your YAML depending on your choice:

• Camel Case:

  decisionMakers:
    - name: John Doe
      role: Manager

• Snake Case:

  decision_makers:
    - name: John Doe
      role: Manager

• Dash Case:

  decision-makers:
    - name: John Doe
      role: Manager

Consistency is key, so choose one style and apply it consistently throughout your YAML files.

---

Nevertheless, the answer is not that complete. I got another recommendation by perpelxity: Use camelCase because of Kubernetes.

[koppor]

A change of the format might be fulfill the requirement given at #75: "Use same format for positives and negatives for both "Outcome" and "Options""

[jonthenerd]

Just giving an opinion here. You seem to be thinking into these GitHub issues, so perhaps you're looking for the internet's feedback...

MADR and ADR are formats that ride on markdown, which uniformly does things with characters you can see on a standard keyboard. Unicode values, while nice to look at (I use them a lot day to day, as well as within my own GitHub / Markdown), are not as clear in their meaning as a word (👍 vs. Pro or Good ). My own preference and what I believe is closer to the intent of Markdown is to use structured text that's well understood how to type and use, vs. a Unicode value that requires special keystrokes to achieve and may not visible in some editors or viewing situations.

Given usage of text, I see that there could be advantages to supporting different options for specifying good/bad or pro/con. However, if you wanted to say provide additional capability in a tool on top of each pro or con, you'd want them separated per line to do so in the markdown vs. having them all on the same line (e.g. "Pros: x, y, z"). Perhaps support for both multiple prefix words that equate to positive and negative would be good?

Something like the following?

### {title of option}
* Good, because ....
* Pro: because ....
* Positive: because...
* Bad, because ...
* Con: because ...
* Negative: because...

If you did something like this, teams could mix/match as it made sense, or document what they wanted their convention to be in such a way as for tooling to pick it up and use it by default.

Just random thoughts from the internet. Thanks for doing all of this work on MADR.

[koppor]

@jonthenerd You are perfectly right with your guess that I seek for community feedback. I did not want to harvest all existing variants out there, because the template should guide and maybe the majority is wrong 😋

What is your thought on

Pros:

• ...

Cons:

• ...

I fully agree that there should be "smart" tool support. There, I am not sure whether I should use JavaScript (and try to improve existing tooling), use Python or Java (which I know best and use for scripting, too)

My main driver is that the template should be easy to understand and only one variant. OK, maybe for the pro users, there should be "hidden" variants or variantion points or guidelines for those.