Documentation: getting started - changing examples (project-chip#35929)

* Documentation: getting started - changing examples

Add a new documentation file that shows how to change, re-gen and
recompile examples.

* Add to index

* Fix spelling

Author: cecille

docs/getting_started/changing_examples.md

@@ -0,0 +1,64 @@
+# Changing Examples
+
+The composition of most examples in the SDK is static and code generated.
+
+The tool used to describe and change the composition of an example is called
+ZAP. More information about ZAP and a walk-through of the tool can be found in
+the [ZAP introduction](./zap.md). The composition of the device is captured in a
+.zap file, which is readable by the ZAP tool. This is then compiled into a
+human-readable .matter file, which is used to build the static features of the
+example.
+
+To change the composition of a device example, you need to
+
+1. Change the zap file to implement your desired changes
+2. Run the code generation tool to generate the .matter file
+3. Re-build the example
+
+## Changing the zap file in an example
+
+Most examples in the SDK keep the .zap file in a sub-directory called
+example-name-common (ex. lighting-common). To load an existing .zap file into
+the ZAP tool, from the chip-root use
+
+```
+./scripts/tools/zap/run_zaptool.sh <location of the .zap file>
+```
+
+For example, to make changes to the lighting app, use:
+
+```
+./scripts/tools/zap/run_zaptool.sh examples/lighting-app/lighting-common/lighting-app.zap
+```
+
+This will open the ZAP GUI tool, which can be used to change the endpoint
+composition, clusters, features, attributes, commands and events exposed by the
+device.
+
+Details of how to use the tool can be found in the [ZAP Introduction](./zap.md).
+
+## Running code generation
+
+To compile the .matter file for use in building, use:
+
+```
+./scripts/tools/zap/generate.py <location of the .zap file>
+```
+
+For example, for changes to the lighting app, use:
+
+```
+./scripts/tools/zap/generate.py examples/lighting-app/lighting-common/lighting-app.zap
+```
+
+If there are changes to many .zap files, the following script can be used to
+recompile the .zap files for all the examples and the controller.
+
+```
+ ./scripts/tools/zap_regen_all.py
+```
+
+## Rebuilding the example
+
+After generating the .matter file, re-build the example. Instructions for
+building examples are given in [Building your first example](./first_example.md)

docs/getting_started/index.md

@@ -12,5 +12,6 @@ The following docs are a brief introduction to SDK development.
 ```
 
 -   [Running your first example](./first_example.md)
--   [SDK Basics](./SDKBasics.md)
--   [ZAP](./zap.md)
+-   [Changing examples](./changing_examples.md)
+-   [SDK Architecture Introduction](./SDKBasics.md)
+-   [ZAP Introduction](./zap.md)