Add design style guide and a description of what belongs in the design versus in a proposal document. (#649)

Expand the description of the structure of a proposal PR. Clarify that
the full PR is the proposal, not only the P-numbered document. Start a
design style guide and use it to describe which parts of a proposal
should not end up in the design.

Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com>
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>

docs/design/README.md

@@ -10,6 +10,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 ## Table of contents
 
+-   [Overview](#overview)
 -   [Context and disclaimer](#context-and-disclaimer)
     -   [Example code](#example-code)
 -   [Basic syntax](#basic-syntax)
@@ -68,6 +69,24 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 <!-- tocstop -->
 
+## Overview
+
+This documentation describes the design of the Carbon language, and the
+rationale for that design. The goal is to provide sufficient coverage of the
+design to support the following audiences:
+
+-   People who wish to determine whether Carbon would be the right choice to use
+    for a project compared to other existing languages.
+-   People working on the evolution of the Carbon language who wish to
+    understanding the rationale and motivation for existing design decisions.
+-   People working on a specification or implementation of the Carbon language
+    who need a detailed understanding of the intended design.
+-   People writing Carbon code who wish to understand why the language rules are
+    the way they are.
+
+For Carbon developers, documentation that is more suitable for learning the
+language will be made available separately.
+
 ## Context and disclaimer
 
 Eventually, this document hopes to provide a high-level overview of the design

docs/project/design_style_guide.md

@@ -0,0 +1,98 @@
+# Language design style guide
+
+<!--
+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)
+-   [General](#general)
+-   [Linking](#linking)
+-   [Document structure](#document-structure)
+    -   [Overview and detailed design](#overview-and-detailed-design)
+    -   [Alternatives considered](#alternatives-considered)
+    -   [References](#references)
+
+<!-- tocstop -->
+
+## Background
+
+The [language design](/docs/design) documentation in the Carbon project should
+use a consistent style and tone, and should read as if it were written by a
+single author. This document describes structural, stylistic, and formatting
+conventions for the language design, where they have been established.
+
+## General
+
+The language design documentation follows the
+[style conventions](/CONTRIBUTING.html#google-docs-and-markdown) for Carbon
+documentation.
+
+## Linking
+
+-   Links to issues and to complete proposals should use the text `#nnnn`, where
+    `nnnn` is the issue number, optionally followed by the proposal title, and
+    should link to the issue or pull request on GitHub. For example,
+    `[#123: widget painting](https://github.com/carbon-language/carbon-lang/pull/123)`.
+-   Links to specific sections of a proposal should link to the repository copy
+    of the proposal file, using the section title or other appropriate link
+    text. For example,
+    `[Painting details](/docs/proposals/p0123.md#painting-details)`
+
+## Document structure
+
+Documents within the language design should usually be divided into the
+following sections, with suitable level-two (`##`) headings:
+
+-   **Table of contents** (auto-generated)
+-   **TODO** (optional)
+-   **Overview**
+-   Zero or more detailed design sections
+-   **Alternatives considered**
+-   **References**
+
+### Overview and detailed design
+
+The overview should describe the high-level concepts of this area of the design,
+following BLUF principles. Where the overview does not fully cover the detailed
+design, additional sections can be added as needed to more completely describe
+the design.
+
+The aim of these sections is to describe the design choices that have been made,
+how those choices fit into the overall design of Carbon, the rationale for those
+choices, and how and why those choices differ from other languages to which
+Carbon is likely to be compared, particularly C++, Rust, and Swift.
+
+### Alternatives considered
+
+This section should provide bullet points briefly describing alternative designs
+that were considered, along with references to the proposals in which those
+designs were discussed. For example:
+
+```md
+-   [Paint widgets from bottom to top](/docs/proposals/p0123.md#alternatives-considered).
+```
+
+### References
+
+This section should provide bullet points linking to the following:
+
+-   External documents providing background on the topic or additional useful
+    information.
+-   Each proposal that contributed to the design described in this document.
+
+For example:
+
+```md
+-   [Wikipedia example page](https://en.wikipedia.org/wiki/Wikipedia:Example)
+-   Proposal
+    [#123: widget painting](https://github.com/carbon-language/carbon-lang/pull/123).
+```
+
+Links to related parts of the design should be included inline, where relevant,
+not in the references section.

docs/project/evolution.md

@@ -20,6 +20,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
         -   [Carbon leads](#carbon-leads)
     -   [When to write a proposal](#when-to-write-a-proposal)
     -   [Proposal PRs](#proposal-prs)
+        -   [What goes in the proposal document](#what-goes-in-the-proposal-document)
         -   [Open questions](#open-questions)
     -   [Review and RFC on proposal PRs](#review-and-rfc-on-proposal-prs)
     -   [Blocking issues](#blocking-issues)
@@ -254,8 +255,11 @@ a pull request instead go through the full evolution process.
 A proposal PR should use the `proposal` label, have a descriptive title, and
 easily understood initial summary comment. Authors and leads are encouraged to
 edit both as necessary to ensure they give the best high-level understanding of
-the proposal possible. The proposals should then use the
-[template file](/proposals/template.md) to describe itself fully.
+the proposal possible.
+
+A proposal PR will include a "P-numbered" _proposal document_,
+`proposals/pNNNN.md`, where `NNNN` is the pull request number. This file should
+be based on the [proposal template file](/proposals/template.md).
 
 When writing a proposal, try to keep it brief and focused to maximize the
 community's engagement in it. Beyond the above structure, try to use
@@ -263,11 +267,38 @@ community's engagement in it. Beyond the above structure, try to use
 or [BLUF](<https://en.wikipedia.org/wiki/BLUF_(communication)>) writing style to
 help readers rapidly skim the material.
 
-Proposal PRs will often lead to related changes to the rest of the Carbon
-project. These changes may be added to the proposal PR itself, they may be done
-in other PRs that are referenced for context, or they may be stand-alone changes
-that are implemented through a series of future PRs to the rest of the project.
-All of these options are fine.
+#### What goes in the proposal document
+
+The purpose of the proposal document is to present the case for deciding to
+adopt the proposal. Any information that feeds into making that decision, and
+that should not be maintained as part of our living design documentation,
+belongs in the proposal document. This includes background material to introduce
+the problem, comparisons to any alternative designs that were considered and any
+other current proposals in the same area, records of informal polls taken to
+determine community preferences, and rationale for the decision based on the
+project's goals.
+
+The proposal PR can contain related changes to the Carbon project, such as
+updates to the design documentation. Those changes form part of the proposal,
+and need not be additionally described in the proposal document beyond a mention
+in the "Proposal" section that such changes exist. For example:
+
+```md
+## Proposal
+
+See the proposed changes to the design documents.
+```
+
+Readers of proposals are expected to consult the PR or the git commit that
+merged the PR in order to understand the proposed changes.
+
+The author of a proposal is not required to include changes to the design
+documentation as part of a proposal, and it may in some cases be preferable to
+decouple the proposal process from updating the design. When accepted, the
+proposal would then be implemented through a series of future PRs to the rest of
+the project, and the proposal document should describe what is being proposed in
+enough detail to validate that those future PRs properly implement the proposed
+direction.
 
 #### Open questions