From ecaa192929e5fcb78e4f5436393fa6f02036bd0f Mon Sep 17 00:00:00 2001
From: Elliott Hughes <enh@google.com>
Date: Tue, 4 Jun 2024 18:20:05 +0000
Subject: [PATCH] Add a README.md to docs/, as a guide to what we have
 available.

I was actually here to add some new documentation, but realized there wasn't really a good place to put it...

Change-Id: I8a2fc93e61a89e87aa53dd0beb9dfcc6561687ca
---
 README.md      | 12 ++++--------
 docs/README.md | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 8 deletions(-)
 create mode 100644 docs/README.md

diff --git a/README.md b/README.md
index 0ad06a8b1..0f2c30fda 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,11 @@
-# bionic
+# bionic maintainer overview
 
 [bionic](https://en.wikipedia.org/wiki/Bionic_(software)) is Android's
 C library, math library, and dynamic linker.
 
-# Using bionic as an app developer
-
-See the [user documentation](docs/).
-
-# Working on bionic itself
-
-This documentation is about making changes to bionic itself.
+This document is a high-level overview of making changes to bionic itself.
+If you're trying to _use_ bionic, or want more in-depth information about
+some part of the implementation, see [all the bionic documentation](docs/).
 
 ## What are the big pieces of bionic?
 
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..2825eac4e
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,34 @@
+# bionic documentation
+
+[bionic](https://en.wikipedia.org/wiki/Bionic_(software)) is Android's
+C library, math library, and dynamic linker.
+
+## User documentation
+
+* [Android bionic status](status.md) - where we are in terms of standards,
+  and what changed with each OS release.
+* [32-bit ABI bugs](32-bit-abi.md) - historical accidents we can never fix.
+* [`EINTR`](EINTR.md) - what is the `EINTR` failure,
+  and how can code deal with it?
+* [When to use which `#define`](defines.md) - how to choose between
+  `__ANDROID__` and `__BIONIC__` and all the other options for conditional
+  compilation.
+* [fdsan](fdsan.md) - bionic's file descriptor sanitizer,
+  which detects use-after-close() bugs.
+* [fdtrack](fdtrack.md) - bionic's file descriptor tracker,
+  which helps debug file descriptor leaks.
+
+## Maintainer documentation
+
+If you're trying to make changes to bionic _itself_, start with the
+[bionic maintainer documentation](../README.md).
+
+We also have more detail on several specific parts of the implementation:
+
+* [The anatomy of bionic's `_FORTIFY_SOURCE`](clang_fortify_anatomy.md) -
+  how does `_FORTIFY_SOURCE` work on bionic (primarily "with clang").
+* [Android ELF TLS](elf-tls.md) - details of bionic's ELF TLS implementation.
+* [Validating libc assembler](libc_assembler.md) - how to test changes to
+  libc assembler routines.
+* [Validating native allocator changes](native_allocator.md) - how to test
+  changes to the native allocator.