changes to README files
diff --git a/README.md b/README.md
index 1633d00..10f3520 100644
--- a/README.md
+++ b/README.md
@@ -20,11 +20,13 @@
- [Creating a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request#creating-the-pull-request)
- [Documentation](docs/)
- - [Data models](docs/data.md)
- - [EZT templates](docs/ezt.md)
- - [Creating content](docs/markdown.md)
- - [Processing](docs/process.md)
+ - [Data models](docs/data.md) - how the global data model works and how to enhance your data.
+ - [EZT templates](docs/ezt.md) - how ezt templates convert global data into content.
+ - [Creating content](docs/markdown.md) - how to create markdown and mix it with html.
+ - [Processing](docs/process.md) -
- [Preview/feature branches](docs/branches.md)
+ - Local builds
+
The website is built with [Pelican](https://blog.getpelican.com).
CI/CD is via a [.asf.yaml file](https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features).
diff --git a/docs/README.md b/docs/README.md
index a6aeac9..eb9139f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,11 +1,22 @@
# Documentation
1. [Data Model](data.md)
+ How the global data model works and how to enhance the data availble for your content.
2. [EZT](ezt.md)
+ How EZ Templates are used convert global data into content.
3. [Markdown](markdown.md)
+ How your content is converted to HTML.
4. [Processing](process.md)
+ How the process works to create the HTML.
-5. [Preview Branching](branches.md)
\ No newline at end of file
+5. [Preview Branching](branches.md)
+ How to work on complex changes like updated templates, new data sources, and alternative content.
+
+6. Local Builds
+ How to setup your local environment to work on a branch.
+
+7. Error Analysis
+ How to track down errors in your build.
\ No newline at end of file
diff --git a/theme/apache/templates/README.md b/theme/apache/templates/README.md
index a3ac783..9519647 100644
--- a/theme/apache/templates/README.md
+++ b/theme/apache/templates/README.md
@@ -7,8 +7,8 @@
## Page Templates
-1. base.html - the main template. Other templates extend this template.
-2. page.html - need to override pelican's default page.html which automatically includes `<h1>{{ page.title }}</h1>`
+1. base.html - the main template. Other templates extend this template automatically even those in the default pelican thme.
+2. page.html - this overrides pelican's default page.html which includes `<h1>{{ page.title }}</h1>`. We don't want that behavior.
Change the base page as necessary and add new page types as required.
@@ -21,7 +21,11 @@
Each of the above files should be edited as needed for the deployed website.
-## Pelican Variables set in [pelicanconf.py](../../../pelicanconf.py)
+## Pelican Settings
+
+Pelican settings are provided in the [pelicanconf.py](../../../pelicanconf.py) file.
+
+Some settings inlude:
~~~python
SITEURL = 'https://www.apache.org'
@@ -29,11 +33,13 @@
CURRENTYEAR = date.today().year
~~~
+The file contains helpful comments about the settings.
+
## Pelican Themes
This is a [custom theme][1]. Pelican templates use [Jinja][2]
-## Apache CMS
+## History - Apache CMS
The [svn history](http://svn.apache.org/viewvc/infrastructure/site/trunk/templates) was not migrated and remains available.
