Update docs/ READMEs (#1211)

With a focus on making each README a good representation for its directory, and adding links.

Co-authored-by: Richard Smith <richard@metafoo.co.uk>

docs/README.md

@@ -11,4 +11,46 @@ These documents cover all aspects of Carbon ranging from the project down to
 detailed designs for specific language features.
 
 If you're trying to learn more about Carbon, we recommend starting at
-/README.md.
+[`/README.md`](/README.md).
+
+## Design
+
+The design of the Carbon language, and the rationale for that design, is
+documented in the [`design/` directory](design/README.md). This documentation is
+intended to support these 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.
+
+This is in contrast to [proposals](/proposals/README.md), which document the
+individual decisions that led to this design (along with other changes to the
+Carbon project), including the rationale and alternatives considered.
+
+## Project
+
+The [`project/` directory](project/README.md) contains project-related
+documentation for Carbon, including:
+
+-   [goals](project/goals.md), and the
+    [principles](project/principles/README.md) and [roadmap](project/roadmap.md)
+    derived from those goals,
+-   how the project works, and
+-   how to contribute.
+
+## Guides
+
+The [`guides/` directory](guides/README.md) contains **to-be-written** end-user
+documentation for developers writing programs in Carbon.
+
+## Spec
+
+The [`spec/` directory](spec/) contains the **to-be-written** formal
+specification of the Carbon language. This is for implementers of compilers or
+other tooling. This is intended to complement the interactive language explorer
+tool (TODO: link).

docs/design/README.md

@@ -75,20 +75,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 ## 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.
+rationale for that design.
 
 ## Context and disclaimer
 
@@ -122,10 +109,8 @@ themselves) is also important. It is both an important signal but also a bias.
 
 ### Example code
 
-In order to keep example code consistent, we are making choices that may change
-later. In particular, where `$` is shown in examples, it is a placeholder: `$`
-is a well-known bad symbol due to international keyboard layouts, and will be
-cleaned up during evolution.
+Some syntax used in example code is provisional or placeholder, and may change
+later.
 
 ## Basic syntax
 
@@ -837,7 +822,7 @@ be used to instantiate the parameterized definition with the provided arguments
 in order to produce a complete type. For example:
 
 ```carbon
-class Stack(T:$$ Type) {
+class Stack(template T:! Type) {
   var storage: Array(T);
 
   fn Push(value: T);
@@ -867,7 +852,7 @@ arguments. The runtime call then passes the remaining arguments to the resulting
 complete definition.
 
 ```carbon
-fn Convert[T:$$ Type](source: T, U:$$ Type) -> U {
+fn Convert[template T:! Type](source: T, template U:! Type) -> U {
   var converted: U = source;
   return converted;
 }

docs/design/templates.md

@@ -44,11 +44,11 @@ are subject to full instantiation -- other parameters will be type checked and
 bound early to the extent possible. For example:
 
 ```
-class Stack(Type$$ T) {
-  var Array(T) storage;
+class Stack(template T:! Type) {
+  var storage: Array(T);
 
-  fn Push(T value);
-  fn Pop() -> T;
+  fn Push[addr me: Self*](value: T);
+  fn Pop[addr me: Self*]() -> T;
 }
 ```
 
@@ -59,23 +59,23 @@ instantiation.
 
 ### Functions with template parameters
 
-Both implicit and explicit function parameters in Carbon can be marked as
+Both deduced and explicit function parameters in Carbon can be marked as
 template parameters. When called, the arguments to these parameters trigger
 instantiation of the function definition, fully type checking and resolving that
-definition after substituting in the provided (or computed if implicit)
+definition after substituting in the provided (or computed if deduced)
 arguments. The runtime call then passes the remaining arguments to the resulting
 complete definition.
 
 ```
-fn Convert[Type$$ T](T source, Type$$ U) -> U {
-  var U converted = source;
+fn Convert[template T:! Type](source: T, template U:! Type) -> U {
+  var converted: U = source;
   return converted;
 }
 
-fn Foo(Int i) -> Float {
-  // Instantiates with the `T` implicit argument set to `Int` and the `U`
-  // explicit argument set to `Float`, then calls with the runtime value `i`.
-  return Convert(i, Float);
+fn Foo(i: i32) -> f32 {
+  // Instantiates with the `T` deduced argument set to `i32` and the `U`
+  // explicit argument set to `f32`, then calls with the runtime value `i`.
+  return Convert(i, f32);
 }
 ```
 

docs/guides/README.md

@@ -6,5 +6,7 @@ Exceptions. See /LICENSE for license information.
 SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -->
 
-This directory contains end user documentation on how to use Carbon. These
-should be focused on people trying to use and write code in Carbon.
+This directory contains end-user documentation on how to use Carbon, focused on
+people trying to use and write code in Carbon.
+
+-   [Glossary](glossary.md)

docs/project/README.md

@@ -7,4 +7,19 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -->
 
 This directory contains project-related documentation for Carbon. Information
-about how the project works, goals and community information belong here.
+about how the project works, goals, and community information belong here.
+
+-   [Goals](goals.md), and [principles](principles/README.md) derived from those
+    goals
+-   [Roadmap](roadmap.md) and the [process](roadmap_process.md) for updating it
+-   Carbon's process for [evolution and governance](evolution.md)
+-   [Criteria for Carbon to go public](going_public.md)
+-   [Groups](groups.md) used for contacting key contributors and determining
+    access
+-   Contributing to Carbon:
+    -   [Tools used when contributing to Carbon](contribution_tools.md)
+    -   Style guides for [language design](design_style_guide.md) and
+        [C++ code](cpp_style_guide.md)
+    -   How Carbon does [code review](code_review.md)
+    -   [Trunk-based pull-request GitHub workflow](pull_request_workflow.md)
+        used by Carbon

docs/project/principles/README.md

@@ -20,3 +20,11 @@ principle can help achieve consistency across those multiple designs.
 
 Note that these principles seek to establish both the approaches the project
 wants to pursue, as well as those we want to exclude.
+
+-   [Errors are values](error_handling.md)
+-   [Information accumulation](information_accumulation.md)
+-   [Low context-sensitivity](low_context_sensitivity.md)
+-   [Prefer providing only one way to do a given thing](one_way.md)
+-   [Safety strategy](safety_strategy.md)
+-   [One static open extension mechanism](static_open_extension.md)
+-   [Success criteria](success_criteria.md)