Progressive disclosure principle (#5661)

This proposal codifies our preference for designs that support
"progressive
disclosure", meaning that programmers can ignore a given language
concept (or
even be unaware of it) until it is directly relevant to the task they're
doing.

docs/project/principles/progressive_disclosure.md

@@ -0,0 +1,49 @@
+# Principle: Progressive disclosure
+
+<!--
+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
+-->
+
+<!-- toc -->
+
+## Table of contents
+
+-   [Background](#background)
+-   [Principle](#principle)
+-   [Applications of this principle](#applications-of-this-principle)
+
+<!-- tocstop -->
+
+## Background
+
+[Progressive disclosure](https://en.wikipedia.org/wiki/Progressive_disclosure)
+is a UX design pattern which defers revealing information and advanced/
+special-case controls to the user until they are relevant to the current task,
+in order to make the system easier to learn and use. Although the term
+originates in GUI design, it can be applied to language design as well. In
+particular, it's one of
+[Swift's core design principles](https://www.youtube.com/watch?v=CRtyWqwLM3M&t=369s).
+
+## Principle
+
+In Carbon, we will prefer designs that support progressive disclosure, in the
+sense defined
+[here](https://www.douggregor.net/posts/swift-for-cxx-practitioners-extensions/#:~:text=By%20default%2C%20any%20code,understanding%20of%20the%20language):
+
+> ... the idea that one can ignore certain aspects of the language when starting
+> out, and then learn about them only at the time when you need them, without
+> invalidating any of your prior understanding of the language.
+
+## Applications of this principle
+
+Types such as `i32` are designed to follow progressive disclosure: they are
+actually class types defined in the prelude library that support arithmetic
+operations by implementing certain customization interfaces. However,
+programmers can learn to use them by thinking of them as primitive types like
+their C counterparts, without needing to understand the arithmetic operator
+interfaces, interface implementation in general, libraries, the prelude, or even
+class types. Subsequently learning those concepts doesn't invalidate that
+original mental model, but rather shows how that model is built out of more
+fundamental pieces.

proposals/p5661.md

@@ -0,0 +1,58 @@
+# Progressive disclosure principle
+
+<!--
+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/5661)
+
+<!-- toc -->
+
+## Table of contents
+
+-   [Abstract](#abstract)
+-   [Problem](#problem)
+-   [Proposal](#proposal)
+-   [Rationale](#rationale)
+
+<!-- tocstop -->
+
+## Abstract
+
+This proposal codifies our preference for designs that support "progressive
+disclosure", meaning that programmers can ignore a given language concept (or
+even be unaware of it) until it is directly relevant to the task they're doing.
+
+## Problem
+
+Carbon's design choices have been motivated in part by a desire for "progressive
+disclosure", but that approach has not been codified as a design principle.
+
+## Proposal
+
+See
+(`docs/project/principles/progressive_disclosure.md`)[/docs/project/principles/progressive_disclosure.md],
+which is introduced by this proposal.
+
+## Rationale
+
+In order to have a vibrant
+[community and culture](/docs/project/goals.md#community-and-culture), Carbon
+needs to be effectively teachable and learnable. Progressive disclosure supports
+that goal by minimizing the amount that must be learned at any one time, and by
+enabling concepts to be introduced when they are most salient to the programmer.
+
+Relatedly, although
+["lies-to-children"](https://en.wikipedia.org/wiki/Lie-to-children) can be an
+appropriate teaching tool, they also risk undermining the health of the
+community by creating distance between those who know the full truth and those
+who have only been taught the "lie". This principle helps minimize that risk,
+through the expectation that progressive disclosure not invalidate the
+programmer's prior understanding of the language.
+
+Finally, this principle helps make Carbon code
+[easy to read, understand, and write](/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write),
+by minimizing the amount of Carbon knowledge that a programmer needs in order to
+read, understand, or write a given piece of code.