diff --git a/README.md b/README.md
index 7e62085..951e713 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,131 @@
+# 🧠 hippunfold_surf
 
+This package provides plotting functions for hippocampal surface maps from HippUnfold (https://github.com/khanlab/hippunfold), 
+wrapping the Nilearn (https://nilearn.github.io) plotting functions (matplotlib engine) to achieve this. 
 
-# examples
-```
-label_gii = 'tpl-avg_label-hippdentate_density-{density}_subfields.label.gii'
+Note: these plotting functions are distinct from those in HippoMaps (https://github.com/MICA-MNI/hippomaps), which use 
+VTK wrappers and have a number of limitations therein. 
+
+This package is new and still under active development so suggestions and pull-requests are welcome!
 
-density='1mm'
-fig = plot_hippdentate(label_gii.format(density=density),hemi=None,density=density,view='dorsal')
-fig = plot_hippdentate(label_gii.format(density=density), hemi=None,density=density,view='ventral')
-```
 
+## 📦 Installation
 
+To install the package, simply run:
+
+```sh
+pip install hippunfold_plot
 ```
-fig = plot_hippdentate(label_gii.format(density=density),hemi='left',density=density,view='dorsal')
+
+## 🚀 Usage
+
+Here are some examples of how to use the `plot_hipp_surf` function to visualize hippocampal surface maps.
+
+### Example 1: Plot Both Hemispheres
+
+```python
+from plotting import plot_hipp_surf
+from hippunfold_plot.utils import get_resource_path
+
+#get subfields for demonstrating plotting
+label_gii = get_resource_path('tpl-avg_label-hippdentate_density-{density}_subfields.label.gii')
+density = '1mm'
+
+# Plot dorsal view
+fig = plot_hipp_surf(label_gii.format(density=density), hemi=None, density=density, view='dorsal')
 fig.show()
-fig = plot_hippdentate(label_gii.format(density=density),hemi='right',density=density,view='dorsal')
+
+# Plot ventral view
+fig = plot_hipp_surf(label_gii.format(density=density), hemi=None, density=density, view='ventral')
 fig.show()
 ```
 
+### Example 2: Plot Left and Right Hemispheres Separately
+
+```python
+from plotting import plot_hipp_surf
+from hippunfold_plot.utils import get_resource_path
 
+#get subfields for demonstrating plotting
+label_gii = get_resource_path('tpl-avg_label-hippdentate_density-{density}_subfields.label.gii')
+density = '1mm'
+
+# Plot left hemisphere
+fig = plot_hipp_surf(label_gii.format(density=density), hemi='left', density=density, view='dorsal')
+fig.show()
+
+# Plot right hemisphere
+fig = plot_hipp_surf(label_gii.format(density=density), hemi='right', density=density, view='dorsal')
+fig.show()
 ```
-fig = plot_hippdentate(label_gii.format(density=density),space='unfold',hemi='left',density=density,view='dorsal')
+
+### Example 3: Plot Unfolded Space
+
+```python
+from plotting import plot_hipp_surf
+from hippunfold_plot.utils import get_resource_path
+
+#get subfields for demonstrating plotting
+label_gii = get_resource_path('tpl-avg_label-hippdentate_density-{density}_subfields.label.gii')
+density = '1mm'
+
+# Plot left hemisphere in unfolded space
+fig = plot_hipp_surf(label_gii.format(density=density), space='unfold', hemi='left', density=density, view='dorsal')
 fig.show()
-fig = plot_hippdentate(label_gii.format(density=density),space='unfold',hemi='right',density=density,view='dorsal')
+
+# Plot right hemisphere in unfolded space
+fig = plot_hipp_surf(label_gii.format(density=density), space='unfold', hemi='right', density=density, view='dorsal')
 fig.show()
 ```
 
+## 🛠️ Functions
+
+### `plot_hipp_surf`
+
+```python
+def plot_hipp_surf(surf_map: Union[str, list], 
+                   density: str = '0p5mm', 
+                   hemi: str = 'left', 
+                   space: Optional[str] = None, 
+                   figsize: Tuple[int, int] = (12, 8), 
+                   dpi: int = 300, 
+                   vmin: Optional[float] = None, 
+                   vmax: Optional[float] = None, 
+                   colorbar: bool = False, 
+                   colorbar_shrink: float = 0.25, 
+                   cmap: Optional[Union[str, plt.cm.ScalarMappable]] = None, 
+                   view: str = 'dorsal', 
+                   avg_method: str = 'median', 
+                   bg_on_data: bool = True, 
+                   alpha: float = 0.1, 
+                   darkness: float = 2, 
+                   **kwargs) -> plt.Figure:
+    """
+    This function plots a surface map of the hippocampus, which can be a label-hippdentate shape.gii, func.gii, or a Vx1 array 
+    (where V is the number of vertices in the hippocampus and dentate). Any arguments that can be supplied to nilearn's plot_surf() 
+    can also be applied here, overriding the defaults set below.    """
+```
+
+## 🧪 Testing
+
+To run the tests, including unit tests and docstring tests, use the following command:
+
+```sh
+python -m unittest discover -s . -p "test_*.py"
+```
+
+## 📄 License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## 🙌 Contributing
+
+We welcome contributions! Please see our [CONTRIBUTING](CONTRIBUTING.md) guidelines for more details.
+
+## 📞 Contact
+
+If you have any questions or feedback, feel free to reach out or post an issue!
+
+---
+
+Happy plotting! 🎉
\ No newline at end of file