Add directory structure description to readme

related to #26

other minor edits:

* minor wording changes
* add line spacing between blocks
* add `shell` to code blocks

Signed-off-by: Kevin Broch <[email protected]>

readme.adoc

@@ -1,6 +1,6 @@
 = RISC-V Specification Template
 
-This repository serves as a blueprint for creating GitHub repositories within the RISC-V organization for the purpose of developing specifications. The template aims to facilitate and standardize the process of specification development.
+This repository serves as a template for creating GitHub repositories within the RISC-V organization for the purpose of developing specifications. It aims to facilitate and standardize the process of specification development.
 
 NOTE: If you are viewing this in a specification repository, kindly update the title for this section and provide an introduction relevant to your repository.
 
@@ -16,26 +16,38 @@ For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUT
 
 == Building the Document
 
+=== Directory Structure
+
+The following directories are used to organize the contents of this repo:
+
+* `dependencies/`: software dependencies needed to build the specification
+* `docs-resources/`: resources for all specifications sourced from link:.gitmodules[git submodule]
+* `src/`: source files for the specification
+* `build/`: default directory where the build artifacts are generated
+
 === Prerequisites
 
 To build the document, you'll need the following tools installed on your system:
 
 * Make
-* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical
+* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical
 * Docker
 
 === Cloning the Repository
-```
+
+```shell
 git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git
 ```
+
 === Building the Documentation
 
 To start the build process, run:
-```
+
+```shell
 cd ./docs-spec-template && make build
 ```
 
-The Makefile script will check the availability of Docker on your system:
+The link:Makefile[] script will check the availability of Docker on your system:
 
 * If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems.
 * If Docker is not available, the documentation will be built directly on your system using the installed tools.
@@ -47,7 +59,7 @@ The build process utilizes several options, including theming and font settings,
 === Cleaning up
 
 To clean up the generated files, run:
-```
+
+```shell
 make clean
 ```
-This will remove the generated PDF file.