Add idiomatic code performance and developer-facing docs to goals

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 perform reasonably well.** Developers should not
+regularly be required to choose between performance and readability. Although
+some software may require complex code for performance tuning, Carbon's design
+should aim to provide high performance for regular code.
+
 **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
@@ -419,9 +430,11 @@ Cross-file context has an especially damaging effect on the potential
 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.
+**Support incremental compilation and linking, including parallel and
+distributed strategies.** Iteration requires frequent builds. Incremental
+compilation and linking should make these builds faster, particularly if
+relatively little has changed. Breaking apart compilation and linking units also
+enables better scalability options for build systems of large software.
 
 #### Modern OS platforms, hardware architectures, and environments
 
@@ -435,11 +448,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. This pattern 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 +592,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

@@ -30,5 +30,6 @@ request:
 - [0051 - Goals](p0051.md)
 - [0074 - Change comment/decision timelines in proposal process](p0074.md)
   - [Decision](p0074-decision.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
+and 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 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 belieeve the cost-benefit favors keeping it
+in the goals doc.