Add idiomatic code performance and developer-facing docs to goals (#120)

- [RFC topic](https://forums.carbon-lang.dev/t/rfc-add-idiomatic-code-performance-and-developer-facing-docs-to-goals/105)
- [Decision](https://forums.carbon-lang.dev/t/request-for-decision-add-idiomatic-code-performance-and-developer-facing-docs-to-goals/116)

Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
Co-authored-by: Geoff Romer <gromer@google.com>
Co-authored-by: Dmitri Gribenko <gribozavr@gmail.com>

Most of this is addressing issue #106.

Two new explicit sub-goals:

- Idiomatic code should be performant, stemming from #106.
- User-facing documentation, separate thought from #83 discussion.

I think both of these are on people's minds and assumed, but still worth spelling out.

docs/project/goals.md

@@ -124,6 +124,11 @@ realities. Having the specification will enable better analysis of the language
 as a whole and the production of other partial or full implementations which
 match the behavior of the reference implementation.
 
+**Approachable, developer-facing documentation.** Developers shouldn't be
+expected to read through the specification to ramp up with Carbon. User guides
+and other documentation will be provided to make it easy to learn how to use
+Carbon.
+
 **Compelling adoption tooling.** We want to provide a compelling suite of tools
 out-of-the-box in order to encourage adoption of Carbon at scale where it can
 augment existing C++ codebases. For example, we expect a C++ -> Carbon code
@@ -200,6 +205,11 @@ concerned with ultimate performance at every moment, but in the most constrained
 scenarios they must be able to "open up the hood" without switching to another
 language.
 
+**Idiomatic code should be fast.** Developers should not regularly be required
+to choose between performance and readability. Although performance tuning may
+in rare cases require complex or surprising code, Carbon's design should ensure
+regular, idiomatic code usually results in high performance.
+
 **Code should perform predictably.** The reader and writer of code should be
 able to easily understand its expected performance, given sufficient background
 knowledge of the environment in which it will run. This need not be precise, but
@@ -208,7 +218,7 @@ that performance, whether good or bad, is unsurprising to developers. Even
 pleasant surprises, when too frequent, can become a problem due to establishing
 brittle baseline performance that cannot be reliably sustained.
 
-**Leave no room for a lower level language.** Programmers should not need to
+**Leave no room for a lower level language.** Developers should not need to
 leave the rules and structure of Carbon, whether to gain control over
 performance problems or to gain access to hardware facilities.
 
@@ -325,8 +335,9 @@ primary goal is to support performance-critical software, other kinds of
 software should not be penalized unnecessarily.
 
 > "The right tool for the job is often the tool you are already using -- adding
-> new tools has a higher cost than many people appreciate." --
-> [John Carmack](https://twitter.com/id_aa_carmack/status/989951283900514304)
+> new tools has a higher cost than many people appreciate."
+>
+> -- [John Carmack](https://twitter.com/id_aa_carmack/status/989951283900514304)
 
 **Focus on encouraging appropriate usage of features rather than restricting
 misuse.** Adding arbitrary restrictions to prevent misuse of otherwise general
@@ -359,9 +370,11 @@ well articulated in
 although we may come to different conclusions regarding the principles.
 
 **Design features to be simple to implement.** Syntax, structure, and language
-features should be chosen while keeping the complexity of the implementation
-manageable. This reduces bugs, and will in most cases make the features easier
-to understand.
+features should be chosen while keeping the implementation complexity
+manageable. Simplicity of implementation reduces bugs, and will in most cases
+make the features easier to understand. It's also often the best way to ensure
+predictable performance, although supporting peak performance may require
+options for more complex implementation behavior.
 
 #### Practical safety guarantees and testing mechanisms
 
@@ -420,8 +433,12 @@ distributed build graph options. Without these options, we will again be unable
 to provide fast developer iteration as the codebase scales up.
 
 **Support separate compilation, including parallel and distributed strategies.**
-We cannot assume coarse-grained compilation without blocking fundamental
-scalability options for build systems of large software.
+Iteration requires frequent rebuilds of software as part of the edit/test/debug
+cycle of development. The language design should enable low-latency build
+strategies, particularly when relatively little has changed. This minimally
+requires separate compilation of source files, and potentially other incremental
+build strategies. Separate compilation also enables better scalability options
+for build systems of large software.
 
 #### Modern OS platforms, hardware architectures, and environments
 
@@ -435,11 +452,11 @@ environments.** This goes beyond enabling compile-time translations from one
 abstraction to several implementations. While enabling high-level
 synchronization primitives like mutexes and futures is good, the underlying
 atomic operations provided by the hardware must also be directly available.
-Similarly, lowering parallel constructs into either SIMD or SPMD implementations
-is good but insufficient. Both SIMD and SPMD must be directly addressable in
-Carbon. This pattern repeats across the landscape of hardware, platform, and
-environment, including concurrency versus parallelism more generally, and more
-OS/environment distinctions such as desktop versus mobile versus bare metal.
+Similarly, lowering parallel constructs into a specific implementation, such as
+SIMD or SPMD, is good but insufficient. Multiple parallel implementations must
+be directly addressable in Carbon. The need for native support repeats across
+the landscape of OS platform, hardware, and environment distinctions; for
+example, concurrency versus parallelism, and desktop versus mobile.
 
 **Conversely, Carbon cannot prioritize support for historical platforms.** To
 use a hockey metaphor, we should not skate to where the puck is, much less where
@@ -579,7 +596,7 @@ provide a minimally "correct" migration to very unfriendly code, mechanically
 reproducing exact C++ semantics even if bizarre, even this is not guaranteed and
 improving on it is not a goal. Migration support will prioritize code that
 adheres to reasonable C++ best practices, such as avoiding undefined behavior,
-and having reasonable test coverage that passes under sanitizers.
+maintaining good test coverage, and validating tests with sanitizers.
 
 ### Principles
 

proposals/README.md

@@ -32,5 +32,6 @@ request:
 -   [0074 - Change comment/decision timelines in proposal process](p0074.md)
     -   [Decision](p0074_decision.md)
 -   [0083 - In-progress design overview](p0083.md)
+-   [0120 - Add idiomatic code performance and developer-facing docs to goals](p0120.md)
 
 <!-- endproposals -->

proposals/p0120.md

@@ -0,0 +1,75 @@
+# Add idiomatic code performance and developer-facing docs to goals
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+[Pull request](https://github.com/carbon-language/carbon-lang/pull/120)
+
+## Table of contents
+
+<!-- toc -->
+
+-   [Problem](#problem)
+-   [Proposal](#proposal)
+-   [Justification](#justification)
+-   [Alternatives considered](#alternatives-considered)
+    -   [Use a principle to address performance of idiomatic code](#use-a-principle-to-address-performance-of-idiomatic-code)
+
+<!-- tocstop -->
+
+## Problem
+
+[Issue #106](https://github.com/carbon-language/carbon-lang/issues/106) raises a
+few small issues with the goals doc as approved. Some are small, but in
+particular I'll emphasize the question:
+
+> Do we want to say anything about "reasonably fast by default" or "favors
+> constructs that can be compiled to efficient code" or something like that?
+
+I think this is something that we clearly want for performance, and should be
+laid out.
+
+Additionally, while considering justification for changes in
+[PR 80](https://github.com/carbon-language/carbon-lang/pull/80), I noted there
+is no explicit goal to provide developer-facing documentation. I believe this is
+an intended part of the community goals, and could be inferred from current
+ecosystem text, but may be better if explicit.
+
+## Proposal
+
+Add paragraphs to address performance of idiomatic code and developer-facing
+documentation, as well as making other small fixes.
+
+## Justification
+
+Performance of idiomatic code:
+
+Under "Performance-critical software", we establish that it should be possible
+to write high-performance code with Carbon. However, if taken strictly, we could
+be saying something like "it's okay if idiomatic code is predictably slow, as
+long as developers have tools to 'open up the hood'." That is not the intent,
+and so addressing the case of routine code performance offers the reassurance
+that Carbon will prioritize performance consistently, regardless of whether
+performance tuning is done.
+
+Developer-facing documentation:
+
+"Language tools and ecosystem" addresses the specification and tooling
+explicitly. However, developer-facing documentation is also part of the
+ecosystem, and part of supporting ramp-up training by new Carbon developers.
+Such documentation should be an explicit project priority.
+
+Other changes are incremental improvements to the goal text, and mainly
+presented in this change for consistency of review.
+
+## Alternatives considered
+
+### Use a principle to address performance of idiomatic code
+
+A principle is another way of addressing non-obvious conclusions based on goals.
+However, performance of idiomatic code seems quick to state, and not worth
+splitting off to a separate doc. I believe the cost-benefit favors keeping it in
+the goals doc.