Add instructions on how to create a PR

Author: timothypratley

README.md

@@ -4,44 +4,44 @@
 
 An open effort to structure learning resources with meaningful connections.
 
-Visit the deployed [Clojure Civitas Website](https://clojurecivitas.github.io).
+⚡ No setup – Clone this repo, make a new namespace, start coding.
 
-## Rationale
+✍️ Write as you code – Capture notes, results, and ideas as you go as comments.
 
-See [About Clojure Civitas](https://clojurecivitas.github.io/about).
+🚀 Easy to share – Create a Pull Request, once merged it appears on the [Clojure Civitas Website](https://clojurecivitas.github.io).
 
-## Contributing
-
-Your perspective matters.
+🧠 Build shared knowledge – Your work becomes part of a community resource.
 
-<div style="text-align: center; font-family: 'Georgia', serif; font-size: 1.5rem; margin: 2rem 0; color: #2e7d32;">
-Exploramus, Communicamus, Crescimus<br>
-<small style="font-size: 1rem; color: #555;">We explore, we share, we grow.</small>
-</div>
+🧪 Use Clay – Your normal REPL workflow, but with tables, charts, markdown, and hiccup.
 
-⚡ No setup – Open Civitas, make a new namespace, start coding.
+## Rationale
 
-✍️ Write as you code – Capture notes, results, and ideas as you go.
+*Exploramus, Communicamus, Crescimus*<br>
+<small>We explore, we share, we grow.</small>
 
-🚀 Easy to share – Create a PR, and it gets published.
+See [About Clojure Civitas](https://clojurecivitas.github.io/about).
 
-🧠 Build shared knowledge – Your work becomes part of a growing community resource.
+## Contributing
 
-🧪 Use Clay – Same REPL workflow, but with tables, charts, markdown, and hiccup.
+Your perspective matters.
+Pull Requests invited, that's the point!
 
 ### Write notebooks
 
-Add a notebook in the [`/notebooks`](notebooks) folder.
+Add a notebook (Clojure namespace or markdown file) in the [`/notebooks`](notebooks) folder.
 
-See the [Clay Documentation](https://scicloj.github.io/clay) for information on how to interactively visualize the
-notebook as you write it.
-Author profile can be configured in [clay.edn](clay.edn).
+Configure your author profile in [clay.edn](clay.edn).
 
-### Build the database
+**Optional:** Use [Kindly](https://scicloj.github.io/kindly-noted/kindly) annotations in your notebook to make visualizations
 
-Add to or modify [db.edn](quarto/db.edn)
+```clojure
+^kind/hiccup
+[:svg [:circle {:r 50}]]
+```
+
+**Optional:** Use [Clay](https://scicloj.github.io/clay/#setup) to visualize the notebook as you write it.
 
-### Preview the full website
+**Optional:** Preview the final website
 
 ```sh
 clojure -M:clay -a [:markdown]
@@ -51,10 +51,24 @@ clojure -M:clay -a [:markdown]
 quarto preview site
 ```
 
+[Quarto](https://quarto.org/) is a markdown publishing tool that enhances
+[Pandoc](https://pandoc.org/).
+
 ### Publish
 
 Merged pull requests are shown on the website via a workflow.
 
+To create a pull request
+
+1. fork the repository
+2. make and commit changes in a new branch
+3. push the branch to your fork
+4. and then open a pull request on GitHub to propose merging your changes into the Civitas main branch.
+
+### Building the database
+
+Add to or modify [db.edn](quarto/db.edn)
+
 ## Design
 
 Align with Clojure's values: simplicity, community, and tooling that helps you think.

site/about.qmd

@@ -26,6 +26,13 @@ No infrastructure required.
 </div>
 </div>
 
+"Civitas" refers to a community of citizens, encompassing the rights, duties, and privileges associated with belonging.
+It's a term that signifies citizenship, not just a physical city, but also the political and social fabric of the community.
+
+## Usage
+
+See [README.md](https://github.com/ClojureCivitas/clojurecivitas.github.io/blob/main/README.md).
+
 ## Rationale
 
 Clojure and markdown are a natural fit for interactive, literate programming.
@@ -35,9 +42,9 @@ This friction discourages experimentation and makes publishing harder than it ne
 
 ### Make Publishing Notebooks Easy
 
-[Clay](https://scicloj.github.io/clay/) notebooks combine Clojure and markdown for expressive, interactive literate programming.
+Notebooks combine Clojure and markdown for expressive, interactive literate programming.
 Compared to blogs, gists, or repos, they better support combining narrative, code, and results in a single document.
-Civitas removes the friction of publishing by letting anyone submit notebooks or markdown without setting up a new project or hosting workflow.
+Civitas removes the friction of publishing by enabling you to submit notebooks or markdown without setting up a new project or hosting workflow.
 It provides a shared, well-organized platform for short experiments, tutorials, notes, and blog posts.
 
 ### Build a Database of Knowledge
@@ -78,4 +85,5 @@ See the [Clojure Civitas Analytics Dashboard](https://clojurecivitas.goatcounter
 
 ### Technical Details
 
+Made with [Clay](https://scicloj.github.io/clay/).
 See the [README.md](https://github.com/ClojureCivitas/clojurecivitas.github.io/blob/main/README.md) in the repository for contribution guidelines and technical details.