Skip to content
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

Add FAQ entries for common syntax questions #2011

Merged
merged 5 commits into from
Sep 7, 2022

Conversation

geoffromer
Copy link
Contributor

No description provided.

Copy link
Contributor

@jonmeow jonmeow left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've given some suggestions for rephrasing. I think changing the phrasing a little may help people who are less familiar with Carbon.

docs/project/faq.md Outdated Show resolved Hide resolved
@@ -310,6 +313,84 @@ actively encourage using these languages in those cases. However, we need a
solution for C++ use-cases that require its full performance, low-level control,
and access to hardware.

## Why is Carbon designed that way?
Copy link
Contributor

@jonmeow jonmeow Aug 12, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Why is Carbon designed that way?
## How were specific feature designs chosen?

Small suggestion: "that way" rings a bit disapproving to me, whereas this would be more something we could respond with:
"Throughout the design, we include 'Alternatives considered' and 'References' sections which can be used to research the decision process for a particular design." (like the second paragraph at https://github.com/carbon-language/carbon-lang/blob/trunk/docs/project/faq.md#what-can-i-do-if-i-disagree-with-a-design-decision)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

docs/project/faq.md Outdated Show resolved Hide resolved
docs/project/faq.md Outdated Show resolved Hide resolved
docs/project/faq.md Show resolved Hide resolved
docs/project/faq.md Show resolved Hide resolved
docs/project/faq.md Outdated Show resolved Hide resolved
docs/project/faq.md Show resolved Hide resolved
docs/project/faq.md Outdated Show resolved Hide resolved
docs/project/faq.md Outdated Show resolved Hide resolved
in scope.

It's also worth noting that Carbon doesn't use _any_ kind of brackets to mark
template parameters (or generic parameters), so if Carbon had angle brackets,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
template parameters (or generic parameters), so if Carbon had angle brackets,
[template parameters (and also generic parameters)](https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/README.md#checked-and-template-parameters), so if Carbon had angle brackets,

To my below comment, which I've marked resolved, I do think there should be some link/reference for what is used for template parameters. But maybe this reflects your intent?

(also, suggesting replacing "or" with "and also" to make clear to newcomers that "template" and "generic" aren't two terms for the same thing)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added the link, in a slightly different place.

(also, suggesting replacing "or" with "and also" to make clear to newcomers that "template" and "generic" aren't two terms for the same thing)

That feels awkward because we're inside a negation, and "not (A and B)" conveys less information than "not (A or B)". How about this instead?

docs/project/faq.md Show resolved Hide resolved
docs/project/faq.md Outdated Show resolved Hide resolved
docs/project/faq.md Outdated Show resolved Hide resolved
Copy link
Contributor

@jonmeow jonmeow left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks!

@jonmeow jonmeow merged commit 36a5a52 into carbon-language:trunk Sep 7, 2022
@geoffromer geoffromer deleted the faq branch September 8, 2022 17:40
@chandlerc chandlerc added the documentation An issue or proposed change to our documentation label Jan 13, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation An issue or proposed change to our documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants