-
Notifications
You must be signed in to change notification settings - Fork 413
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Discuss "Good, because" vs. "Pros:" #109
Comments
I also like Unicode. On Windows with Win+., one can have a list of Emojis Thus, why not
|
Maybe we should offer two variants? 😨 |
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" 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:
RecommendationIf 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:
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 #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:
Re: pro/con - I like breaking it out as you've shown for MADR itself. |
(Side track)
There are indeed two tools:
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.
Which means, even no nodejs? bash only? |
My view of "Pros" and "Cons" at #109 (comment)
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"
My view of using emojiI think it's a creative idea, I vote against them.
Off-topic: I would like to see, how other documentation decides on usage of emotions. |
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:"
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)
The text was updated successfully, but these errors were encountered: