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

---

In Gradle discussions 2019, also the "Pro" and "Con" headings were used. See gradle/gradle#10114 (comment)

[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.

[jonthenerd]

I agree on wanting to have one variant be standard, with the possibility of a commented version of that same variant being output if desired by a tool. However, perhaps it is desirable to have this be configurable? MADR itself is a variant on nygard format. Some teams will desire specific inclusion of certain information for their internal purposes. I think any tooling which is developed should come baked with the leading formats, but also capability for addition of formats at the user's discretion.

If tooling is to be developed, I think it would be preferably:

1. cross platform (Mac, leading Linux, and Windows 10+)
2. able to be run without additional framework/infrastructure download
3. extensible by users without code changes to provide their own template variant

Re: pro/con - I like breaking it out as you've shown for MADR itself.

[koppor]

(Side track)

If tooling is to be developed, I think it would be preferably:

There are indeed two tools:

• ADR Manager as web based application. Currently updated to vue3: WIP | Refactor existing parser using typescript adr-manager#164
• VS Code ADR Manager. Variant of ADR Manager for VS Code (https://github.com/adr/vscode-adr-manager)

Moreover, there are some CLI tools, but currently development stalled. I could not find time to continue - and I was thinking to learn Rust while implementing. Maybe, I should just stick with Java and release something. I fell in love with JBang, which enables easy "script" execution if users dare to install jbang itself.

2. able to be run without additional framework/infrastructure download

Which means, even no nodejs? bash only?