diff --git a/docs/project/principles/progressive_disclosure.md b/docs/project/principles/progressive_disclosure.md new file mode 100644 index 000000000000..5d7cecc41329 --- /dev/null +++ b/docs/project/principles/progressive_disclosure.md @@ -0,0 +1,49 @@ +# Principle: Progressive disclosure + + + + + +## Table of contents + +- [Background](#background) +- [Principle](#principle) +- [Applications of this principle](#applications-of-this-principle) + + + +## 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. diff --git a/proposals/p5661.md b/proposals/p5661.md new file mode 100644 index 000000000000..712edb7d6adf --- /dev/null +++ b/proposals/p5661.md @@ -0,0 +1,58 @@ +# Progressive disclosure principle + + + +[Pull request](https://github.com/carbon-language/carbon-lang/pull/5661) + + + +## Table of contents + +- [Abstract](#abstract) +- [Problem](#problem) +- [Proposal](#proposal) +- [Rationale](#rationale) + + + +## 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.