diff --git a/docs/framework/angular/files.md b/docs/framework/angular/files.md
index 69e5225b3f98cc25a281d75762faf21bfaa97d7d..f7acd243556de7842b5461503ebbf375e6a6e239 100644
--- a/docs/framework/angular/files.md
+++ b/docs/framework/angular/files.md
@@ -2,7 +2,7 @@
 
 As a developer working with CiviCRM-Angular, you write *Angular modules* --
 these modules are composed of various JS/CSS/HTML files which define the
-*services*, *directives*, *controllers*, and *HTML partials*.
+*services*, *directives*, *controllers*, and *routes*.
 
 For sake of predictability, these files are placed in the `ang/` folder, and
 they follow a naming convention.
@@ -11,34 +11,39 @@ they follow a naming convention.
     When you generate Angular code via `civix`, the files are
     named according to convention.
 
-    One of the files, `ang/{mymodule}.ang.php` provides instructions for the
-    file-loader.
+    One file, `ang/{mymodule}.ang.php`, provides instructions for the
+    file-loader. It lists any files which match the naming
+    convention.
 
-!!! note "What if my code doesn't follow the naming convention? What if I don't use `civix`?"
+!!! note "What if I don't use `civix`? What if my code doesn't follow the naming convention?"
     The file-loader needs some information about the name and location of
     your AngularJS code, but you don't need to follow the convention.  You
     can configure it via hook.  See: [AngularJS: Loading](/framework/angular/loader.md).
 
 ## Abridged convention
 
-Some Angular modules have a very narrow purpose -- such as defining a
-singular `service` or `directive`. These modules only have 2 or 3 files.
+The abridged convention applies to small Angular modules with a narrow
+purpose -- such as defining a singular `service` or `directive`.  These
+modules only have 2 or 3 files.
 
    * `ang/{mymodule}.ang.php` - General metadata about the module (per [hook_civicrm_angularModules](/hooks/hook_civicrm_angularModules.md)).
-   * `ang/{mymodule}.js` - All Javascript for the module
-   * `ang/{mymodule}.css` - All CSS for the module (if applicable)
+   * `ang/{mymodule}.js` - All Javascript for the module.
+   * `ang/{mymodule}.css` - All CSS for the module (if applicable).
+   * `ang/{mymodule}.md` - Developer documentation about the module (if applicable).
 
 ## Full convention
 
-Some Angular modules have broader purpose -- such as defining a new screen
-with a series of related `directive`s, `controller`s, and `service`s.  Each
-of these elements may have multiple aspects (JS/HTML/CSS).
+The full convention applies to bigger Angular modules which serve a broader
+purpose -- such as defining a new screen with a series of related
+`directive`s, `controller`s, and `service`s. Each of these elements may
+have multiple aspects (JS/HTML/CSS).
 
 __Module Files__
 
    * `ang/{mymodule}.ang.php` - General metadata about the module (per [hook_civicrm_angularModules](/hooks/hook_civicrm_angularModules.md)).
    * `ang/{mymodule}.js` - General metadata about the module.
-   * `ang/{mymodule}.css` - General CSS that applies throughout the module.
+   * `ang/{mymodule}.css` - General CSS that applies throughout the module (if applicable).
+   * `ang/{mymodule}.md` - Developer documentation about the module (if applicable).
 
 __Directive Files__
 
@@ -46,6 +51,7 @@ __Directive Files__
    * `ang/{mymodule}/{FooBar}.html` - The main/default template for the directive (if applicable).
    * `ang/{mymodule}/{FooBar}/{Extra}.html` - If you have multiple templates used by the same directive (e.g. via `ng-include` or conditional logic), then put them in a subdir.
    * `ang/{mymodule}/{FooBar}.css` - Any CSS specifically intended for `mymoduleFooBar` (if applicable).
+   * `ang/{mymodule}/{FooBar}.md` - Developer documentation about the directive (if applicable).
 
 __Controller Files__ (These follow the same convention as directives, but they have the suffix `Ctrl`.)
 
@@ -53,18 +59,15 @@ __Controller Files__ (These follow the same convention as directives, but they h
    * `ang/{mymodule}/{FooBar}Ctrl.html` - The main/default template for the controller (if applicable).
    * `ang/{mymodule}/{FooBar}Ctrl/{Extra}.html` - If you have multiple templates used with the same controller (e.g. via `ng-include` or conditional logic), then put them in a subdir.
    * `ang/{mymodule}/{FooBar}Ctrl.css` - Any CSS specifically intended for `MymoduleFooBarCtrl` (if applicable).
+   * `ang/{mymodule}/{FooBar}Ctrl.md` - Developer documentation about the controller (if applicable).
 
 __Service Files__
 
    * `ang/{mymodule}/{FooBar}.js` - The declaration and logic for a service named `mymoduleFooBar`.
+   * `ang/{mymodule}/{FooBar}.md` - Developer documentation about the service (if applicable).
 
 !!! tip "Tip: Use tilde (`~`) to load HTML templates"
     When writing code for Angular, you might use an expression like
     `{templateUrl: 'https://example.org/FooBar.html'}`.  However,
     constructing a full URL that works in every Civi deployment would be
     complex.  Instead, use the tilde prefix.  For example, `{templateUrl: '~/mymodule/FooBar.html'}`.
-		
-<!--
- Proposed Amendment
- Put documentation and examples for each directive or controller in a `*.md` file, adjacent to the `*.js` file. The format is handy for reading/writing/code-snippets, and it won't bloat the final `*.js` output.
--->