diff --git a/oox/README.md b/oox/README.md
index e3bae26f0a03..73e7449e5602 100644
--- a/oox/README.md
+++ b/oox/README.md
@@ -19,10 +19,11 @@ preset type and the adjustment values, the reset can
 be taken from the shape definition.
 
 example of drawingml preset:
-
+```xml
          <a:prstGeom prst="star5">
            <a:avLst/>
          </a:prstGeom>
+```
 
 example of drawingml custom shape (equal to star5 preset):
 ```xml
@@ -134,11 +135,11 @@ needed.
 In order to convert preset shapes to LO's enhanced custom shape,
 we need to load shape definition of preset shapes. The procedure
 to convert the definition from OOXML spec for LO is documented
-(also a script) in `oox/source/drawingml/customshapes/README.md`.
-The scripts in `oox/source/drawingml/customshapes/` also generate pptx
+in `oox/source/drawingml/customshapes/README.md`.
+The `oox/source/drawingml/customshapes/generate.sh` script generate pptx
 files for single presets and also for all presets
-`cshape-all.pptx`. The cshape-all.pptx file is then loaded into Impress
-build with debug enabled in oox and the command line output contains
+`cshape-all.pptx`. The `cshape-all.pptx` file is then loaded into Impress
+build with debug enabled in `oox` and the command line output contains
 information. The generated definition is `oox-drawingml-cs-presets`.
 
 Check `CustomShapeProperties::initializePresetDataMap()` to see how
@@ -152,9 +153,14 @@ the cshape-all.pptx can be used to test the round trips. there's small
 problem with these pptx as they cannot be imported into powerpoint,
 but that can be fixed quickly. when fixed, we can use it to
 test powerpoint odp export and see how complete it is regarding
-custom shapes. OpenXML SDK tools might help when fixing
-`cshape-all.pptx`
-<http://www.microsoft.com/en-us/download/details.aspx?id=30425>
+custom shapes. OpenXML SDK might help when fixing `cshape-all.pptx`
+
+<https://github.com/OfficeDev/Open-XML-SDK>
+
+Also, "OOXML Viewer VSCode Extension" is a useful tool for debugging
+OOXML documents.
+
+<https://github.com/yuenm18/ooxml-viewer-vscode>
 
 ## Export
 Here is how LO's enhanced custom shapes are exported:
diff --git a/oox/source/drawingml/customshapes/README.md b/oox/source/drawingml/customshapes/README.md
new file mode 100644
index 000000000000..4b79fefc6a24
--- /dev/null
+++ b/oox/source/drawingml/customshapes/README.md
@@ -0,0 +1,19 @@
+# Generating Custom Shape Presets
+
+The Perl code (`generatePresetsData.pl` and `generatePresetsPPTXs.pl`) is used
+to generate the custom shape presets.
+
+The `generate.sh` script which invokes the above Perl files, should be invoked
+from the libreoffice core top-level source folder:
+```
+oox/source/drawingml/customshapes/generate.sh
+```
+The logs will be created in the file:
+```
+oox/source/drawingml/customshapes/custom-shapes.log
+```
+ 
+The output would be placed in this folder:
+```
+oox/source/drawingml/customshapes/pptx/
+```
\ No newline at end of file
diff --git a/oox/source/drawingml/customshapes/generate.sh b/oox/source/drawingml/customshapes/generate.sh
index 2a0cd3e439b8..90e0e09404f7 100755
--- a/oox/source/drawingml/customshapes/generate.sh
+++ b/oox/source/drawingml/customshapes/generate.sh
@@ -1,21 +1,11 @@
 #!/bin/bash
 
-# The Perl code here is used to generate the custom shape presets
-# source code.
-
-# This file is both a README and also, if run as a shell script, does what
-# it describes.
-# It should be invoked from the libreoffice core top-level source folder:
-#   ./oox/source/drawingml/customshapes/generate.sh
-# The logs will be created in the file:
-#   ./oox/source/drawingml/customshapes/custom-shapes.log
+# This script is used to generate the custom shape presets
 
 # We want to exit on errors...
 
 set -o errexit
 
-# To re-generate the code, you need to be on Linux (I think).
-# It is not necessary to do a make test-install, just run from instdir.
 # oox needs to be build with dbglevel=2 so that DEBUG is defined.
 
 make oox.clean && make oox dbglevel=2