adr
Discuss "Good, because" vs. "Pros:"
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 https://github.com/gradle/gradle/issues/10114#issuecomment-516340585
I also like Unicode. On Windows with Win+., one can have a list of Emojis
Thus, why not
- 👍: Pro argument
- 🫤: Neutral argument
- 👎: Con argument
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:
-
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
-
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
-
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.
A change of the format might be fulfill the requirement given at https://github.com/adr/madr/issues/75: "Use same format for positives and negatives for both "Outcome" and "Options""
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.
@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.
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:
- cross platform (Mac, leading Linux, and Windows 10+)
- able to be run without additional framework/infrastructure download
- 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.
(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: https://github.com/adr/adr-manager/pull/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?
My view of "Pros" and "Cons" at https://github.com/adr/madr/issues/109#issuecomment-2165959076
-
Good, because they are structured. I like structured information as a programmer. It's impossible to mix "Good" and "Bad" points in the wrong order. Currently, syntactically it is possible to write "Good, etc.; Bad, etc.; Good, etc.".
-
Bad, because people don't think that structurally (this refs fail of Web 3.0, maybe). The option introduces another level of hierarchy. For me, plainly laid out bullet points are simpler to view.
Hmm, what about separating "Good" and "Bad" with a space? So that instead of one big bullet-points list there are 2 of them (3 with "Neutral")?
Overall view of "Pros" and "Cons"
-
Good, because "Pros" and "Cons" have 4 symbols. That means if the application used to render an ADR uses a monospaced font, it would align prettier :) Though, I think a "Sans" font is used by default, so this "good" (or "pros") argument is not strong.
-
Neutral, because a new symbol
:would be used. This requires a Shift key and going up to 1234... keyboard row. (Sorry, this point might be too obscure :laughing: ). -
Bad (or neutral), because, what about "Neutral" option?
My view of using emoji
I think it's a creative idea, I vote against them.
- Bad, because no proper ASCII support (well, there are code pages (DOS related thing), but if I remember correctly, they are tight to control characters).
- Bad, because there is no easy way to type emojis on keyboard.
Standards like
:laughing:or(laughing)are different from app to app. It is possible to make a "shortcuts" in text/code editors, but I think this introduces another level of complexity - Bad, because different modalities: "text" and "non-verbal emotions".
Off-topic:
I would like to see, how other documentation decides on usage of emotions.
