From 0966c64c5ac94146aadf12d0a31cae71b1df25af Mon Sep 17 00:00:00 2001
From: Kpeale Legbara <66691866+kpeale@users.noreply.github.com>
Date: Fri, 14 Nov 2025 11:21:31 +0100
Subject: [PATCH] docs: refine and expand readme content

---
 readme.md | 55 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 38 insertions(+), 17 deletions(-)

diff --git a/readme.md b/readme.md
index 2107c96..fc4bf46 100644
--- a/readme.md
+++ b/readme.md
@@ -1,46 +1,61 @@
 # Stroll
-***"A Lisp dialect in Python."***
+***"A lightweight Lisp dialect implemented in Python."***
 
 ---
 
 ## ⚙️ Introduction
-Stroll in short is a small Lisp dialect written in python! 
-Like a leisurely walk along the river we hope you enjoy your use and potential contribution to such project!
+Stroll is a small, extensible Lisp dialect written in Python.
+It’s designed to be simple, approachable, and ideal for learning, experimenting, and contributing.
+Whether you’re new to Lisp or exploring interpreter design, Stroll provides a friendly environment to build and grow with the language.
 
-If you’re new to Lisp, check out this [quick intro](https://en.wikipedia.org/wiki/Lisp_(programming_language)).
+
+
+If you’re new to Lisp, check out our  [introductory guide](https://en.wikipedia.org/wiki/Lisp_(programming_language)).
 
 ---
 
 ## 🧩 Features
 Here are some of the things **Stroll** currently has to offer!:
 
-### 🧮 Math Operations:
+### 🧮 Math & Comparisons:
 - Basic arithmetic: `+`, `-`, `*`, `/`
-- Comparisons: `>`, `<`, `>=`, `<=`, `==`, `!=`
-- Advanced math: `mod`, `pow`, `sqrt`, `abs`  *(untested)*
+- Comparison operators: `>`, `<`, `>=`, `<=`, `==`, `!=`
+- Additional math functions: `mod`, `pow`, `sqrt`, `abs`  *(some untested)*
 
-### 📦 Working with Data:
+### 📦 Data & Collections:
 - Variables: `let` to store values
 - Lists: `list` to make lists, `append` to add elements
-- List operations: `len`, `reverse`, `index` to manage elements 
+- List utilities: `len`, `reverse`, `index` to manage elements 
 
 ### 🔤 Strings & Text:
-- String creation with quotes
-- String operations: `concat`, `strlen`, `substr`  *(Also untested)*
+- Create strings using quotes
+- String functions: `concat`, `strlen`, `substr`  *(some untested)*
 
 ### 🔁 Control Flow:
-- Conditionals: `if`, `elif`, `else` (Please look in the docs for it is quite different here...)
+- Conditionals: `if`, `elif`, `else` (syntax differs from traditional Lisp — see docs)
 - Loops: `while` loops
-- Logic: `&` (and), `|` (or), `true`, `false`
+- Logic values & operators: `&` (and), `|` (or), `true`, `false`
 
 ### 🖨️ Input/Output:
 - Print to console: `print`
 - Read input: `scan`
 
 ###  👨‍💻 User defined functions:
-- Define function: `fn`
+- Define function with `fn`
 - Set passed in arguments: `argone|argtwo|argthree`
-- Call functions: `call`: call a user defined function
+- Call functions using `call`: call a user defined function
+
+###  Quick Example:
+
+```
+(+ 1 2)
+
+(let x 10)
+(print x)
+
+(fn square |argone| (* argone argone))
+(call square 6)
+```
 
 ---
 
@@ -54,7 +69,13 @@ We’re aiming for:
 ---
 
  ## 🤝 Contributing
-Interested in **Stroll** and want to help it grow?
-Check out our [contributing guide](docs/contributing.md) to get started!
+ Interested in **Stroll** and want to help it grow?
+
+ We welcome contributions of all kinds!
+To get started, please review the contributing guide and explore open issues [contributing guide](docs/contributing.md) to get started! 
+
+If you’d like to add features, improve documentation, or help refine the interpreter, your contributions are appreciated.
+
+
 
 ---