add explaination of how we implement orca
-# Orca: a bot framework for Discord
+# Orca: a bot framework for Discord etc.
## Design
@@ -19,18 +19,23 @@ The primary design goals are:
## Implementation
-Orca is implemented in plain C, but we also use C++'s namespace to
-organize symbols so we could establish 1-1 mappings between Orca APIs
-and supported rest APIs.
+Orca is implemented primarily in plain C, but we also use C++'s
+namespace to organize symbols so we could establish 1-1 mappings
+between Orca APIs and supported REST APIs.
Establishing these 1-1 mappings has two purposes:
1. Reduce the need of documenting every Orca API
2. Reduce our user's cognitive burden of having to read both Orca API
-documenation and supported rest API documentation.
+documenation and supported REST API documentations.
-Orca is implemented with minimum external dependencies to make bot
+Orca is implemented in two parts: All the functions that do the heavy
+lifting are implemented in plain C code. The functions that can be
+mapped to REST APIs are wrapped in C++'s namespace to establish the
+1-1 mappings.
+
+Orca's implemnetation has minimum external dependencies to make bot
deployment deadly simple.
## Build
