improve README.md instructions

README.md

@@ -1,17 +1,23 @@
-# *Who*? 
+<div align="center">
+
+# *Who*? 🦄
+
+![who-banner](https://user-images.githubusercontent.com/194400/194710724-0e2de0b1-0b2a-4ee8-83a0-eb07cce74810.png)
 
 The **quick _answer_** 
 to the question: 
 **_Who_ is in the `@dwyl` community?**
 
+</div>
+
 # **`TODO`**: re-generate the "wall of faces" using latest data
 
 ![face wall](https://user-images.githubusercontent.com/194400/28011265-a95f52d4-6559-11e7-823e-6133d947921a.jpg)
 
 
 # *Why*? 
 
-We needed a **easy/fast/reliable _system_** 
+We needed an **easy/fast/reliable _system_** 
 to **_visualise_ who** is joining
 the **`@dwyl` community** <br />
 so that we can 
@@ -24,8 +30,10 @@ section is *woefully* out of date.
 a while back... 
 but sadly was not made 
 a priority at the time..._)  
-This mini-project addresses 
-[dwyl/start-here/issues/9](https://github.com/dwyl/start-here/issues/9)
+This mini-app/project is designed 
+to scratch our own itch
+and save us
+[time](https://github.com/dwyl/start-here/issues/255).
 
 # *What*?
 
@@ -77,7 +85,7 @@ see:
 [learn-elixir#installation](https://github.com/dwyl/learn-elixir#installation)
 and 
 [learn-postgresql#installation](https://github.com/dwyl/learn-postgresql#installation)
-
+> respectively.
 > **Tip**: check the prerequisites in:
 > [**/phoenix-chat-example**](https://github.com/dwyl/phoenix-chat-example#0-pre-requisites-before-you-start)
 
@@ -87,22 +95,53 @@ in your terminal:
 
 ```sh
 git clone [email protected]:dwyl/app-mvp.git && cd app-mvp
-source .env_sample
 mix setup
 ```
 That will download the **`code`**, 
 install dependencies
 and create the necessary database + tables.
 
-The line 
-`source .env_sample` 
+### Create `.env` file
+
+Create an `.env` file by copying the sample:
+
+```sh
+cp .env_sample .env
+```
+Paste the value of your 
+
 loads the 
 [environment variables](https://github.com/dwyl/learn-environment-variables)
 required to run the App.
 
+### Get your `GitHub` Personal Access Token
+
+To access the **`GitHub` API**,
+you will need to generate a 
+**Personal Access Token**:
+[github.com/settings/tokens](https://github.com/settings/tokens)
+
+Click on the **`Generate new token`** button.
+Name it something memorable
+once you've created the token,
+copy it to your clipboard for the next step.
+
+### Add your `GitHub` token to the `.env` file
 
+Add your token after the `=` sign:
 
-Once the `mix setup` command completes,
+```sh
+export GH_PERSONAL_ACCESS_TOKEN=
+```
+
+Once you've saved your `.env` file,
+run:
+
+```sh
+source .env
+```
+
+Once you have sourced your `.env` file,
 you can run the app with:
 
 ```sh
@@ -129,15 +168,33 @@ a. **Star** the repo on GitHub
 b. **Fork** the repo 
   so you have a copy you can "hack" on. 🍴 <br />
 c. **Clone** the repo to your `localhost` 
-  and run it! (see below) 👩‍💻 <br />
+  and run it! 👩‍💻 <br />
 
 
-For more detail,
+For more detail on contributing,
 please see:
 [dwyl/**contributing**](https://github.com/dwyl/contributing)
 
 ### More Features? 🔔
 
 If you have feature ideas, that's great! 🎉 <br />
-Please _share_ them: 
-[**who/issues**](https://github.com/dwyl/who/issues)
+Please _share_: 
+[**who/issues**](https://github.com/dwyl/who/issues) 🙏
+
+
+<!--
+
+sequenceDiagram
+    Alice->>+John: Hello John, how are you?
+    Alice->>+John: John, can you hear me?
+    John-->>-Alice: Hi Alice, I can hear you!
+    John-->>-Alice: I feel great!
+
+-->
+
+```mermaid
+sequenceDiagram
+    App->>+GitHub: GET @dwyl Organization members
+    GitHub-->>+App: Hi Alice, I can hear you!
+    App-->>-Alice: I feel great!
+```