Add module organization suggestion doc (#6509)

* Add module organization suggestion doc

Suggest one method to keep slang modules organized in the file system.

Closes #4841

3 files changed, 34 insertions, 4 deletions

diff --git a/docs/assets/moduletree.png b/docs/assets/moduletree.png
new file mode 100644
index 000000000..ef8c099a3
--- /dev/null
+++ b/docs/assets/moduletree.png
diff --git a/docs/user-guide/04-modules-and-access-control.md b/docs/user-guide/04-modules-and-access-control.md
index e1976effb..0b4d44e0d 100644
--- a/docs/user-guide/04-modules-and-access-control.md
+++ b/docs/user-guide/04-modules-and-access-control.md
@@ -120,10 +120,6 @@ It is only valid for the user code to `import m`. Attempting to `import helper`
 Multiple `import`s of the same module from different input files will only cause the module to be loaded once (there is no need for "include guards" or `#pragma once`).
 Note that preprocessor definitions in the current file will not affect the compilation of `import`ed code, and the preprocessor definitions in the imported code is not visible to the current file.
 
-> #### Note ####
-> Future versions of the Slang system will support loading of modules from pre-compiled binaries instead of source code.
-> The same `import` keyword will continue to work in that case.
-
 ## Access Control
 
 Slang supports access control modifiers: `public`, `internal` and `private`. The module boundary plays an important role in access control.
@@ -195,6 +191,39 @@ The Slang compiler enforces the following rules regarding access control:
 - Type definitions themselves cannot be `private`, for example, `private struct S {}` is not valid code.
 - `interface` requirements cannot be `private`.
 
+## Organizing File Structure of Modules
+
+Slang does not seek to impose any specific organization of modules. However, there are some conventions that have emerged as being useful.
+
+### Module Organization Suggestions
+
+- The top-level directory contains modules that would be `import`ed by user code.
+- The implementation details of the modules are placed in files at lower levels of the tree.
+
+This has the benefit that it is easy for a user to distinguish the public API from the implementation details.
+
+### Module Organization Example
+
+<img src="../assets/moduletree.png" width="300em" alt="Module organization tree diagram"/>
+
+### Module Organization Example
+
+The above diagram shows a module organization example.
+
+Top-level module files such as `utils.slang` are those that are directly `import`ed by user code. The implementation details of the module are placed in the lower levels of the tree, organized into similarly named subdirectories for clarity.
+
+Modules like `utils.slang` needn't contain anything more than a module declaration and a list of included files, with optional `import` statement(s) to pull in any external dependencies, e.g.
+
+```
+module utils;
+import slangpy;
+
+__include "utils/accumlator.slang";
+__include "utils/tonemap.slang";
+__include "utils/fill.slang";
+```
+
+Here, all the public symbols defined in `accumlator.slang`, `tonemap.slang`, and `fill.slang` are visible to the user of the `utils` module, and these constituent helper files do not need to clutter the top-level file hierarchy.
 
 ## Legacy Modules
 
diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html
index 01e9d09b0..8a314d688 100644
--- a/docs/user-guide/toc.html
+++ b/docs/user-guide/toc.html
@@ -58,6 +58,7 @@
 <li data-link="modules#defining-a-module"><span>Defining a Module</span></li>
 <li data-link="modules#importing-a-module"><span>Importing a Module</span></li>
 <li data-link="modules#access-control"><span>Access Control</span></li>
+<li data-link="modules#organizing-file-structure-of-modules"><span>Organizing File Structure of Modules</span></li>
 <li data-link="modules#legacy-modules"><span>Legacy Modules</span></li>
 </ul>
 </li>