[gjs: 6/8] docs: Write a more hospitable README file

[Philip Chimento <pchimento src gnome org>]

commit a16cd913b1c736644c2fdada53a67365a4da296d
Author: Philip Chimento <philip chimento gmail com>
Date:   Tue Oct 23 08:24:39 2018 -0400

    docs: Write a more hospitable README file
    
    Inspired by the "Code Hospitable" episode of the Greater Than Code
    podcast, and this template:
    https://gist.github.com/nodunayo/c919477906aab6c1af6065ff8e868d3e
    
    Closes #17

 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 49 insertions(+), 20 deletions(-)
---
diff --git a/README.md b/README.md
index 932f9e42..4f3ae39b 100644
--- a/README.md
+++ b/README.md
@@ -10,52 +10,81 @@
 JavaScript bindings for GNOME
 =============================
 
-It's mainly based on Spidermonkey javascript engine and the GObject introspection framework.
-
-Available as part of your GNOME distribution. Powers GNOME Shell, Polari,
-GNOME Documents, and many other apps.
+Use the GNOME platform libraries in your JavaScript programs.
+GJS powers GNOME Shell, Polari, GNOME Documents, and many other apps.
+Under the hood it uses SpiderMonkey, Mozilla's JavaScript engine
+originally developed for Firefox.
 
 Wiki: https://gitlab.gnome.org/GNOME/gjs/wikis/Home
 
-How to build and run if you want to contribute to GJS: see doc/Hacking.md
-
 ## Installation
 
-* TBA
+Available as part of your GNOME distribution by default.
+In most package managers the package will be called `gjs`.
 
 ## Usage
 
-* TBA
+GJS includes a command-line interpreter, usually installed in
+`/usr/bin/gjs`.
+Type `gjs` to start it and test out your JavaScript statements
+interactively.
+Hit Ctrl+D to exit.
+
+`gjs filename.js` runs a whole program.
+`gjs -d filename.js` does that and starts a debugger as well.
+
+There are also facilities for generating code coverage reports.
+Type `gjs --help` for more information.
 
 ## Contributing
 
-1. TBA
+For instructions on how to get started contributing to GJS, please read
+the contributing guide,
+<https://gitlab.gnome.org/GNOME/gjs/blob/master/CONTRIBUTING.md>.
 
 ## History
 
-* TBA
+GJS probably started in August 2008 with [this blog post][havocp] and
+[this experimental code][gscript].
+GJS in its current form was first developed in October 2008 at a company
+called litl, for their [litl webbook] product.
+It was soon adopted as the basis of [GNOME Shell]'s UI code and
+extensions system and debuted as a fundamental component of GNOME 3.0.
 
-## Approaches
+In February 2013 at the GNOME Developer Experience Hackfest GJS was
+declared the ['first among equals'][treitter] of languages for GNOME
+application development.
+That proved controversial for many, and was later abandoned.
 
-* TBA
-  * TBA
+At the time of writing (2018) GJS is used in many systems including
+Endless OS's [framework for offline content][eos-knowledge-lib] and, as
+a forked version, [Cinnamon].
 
 ## Reading material
 
 ### JavaScript & SpiderMonkey
 
-* TBA
+* https://github.com/spidermonkey-embedders/spidermonkey-embedding-examples
 
-### Gnome Contribution
+### GNOME Contribution
 
 * https://wiki.gnome.org/GitLab
 * https://wiki.gnome.org/Newcomers/
 
-## Walkthroughs
-
-* TBA
-  * TBA
-
 ## License
 
 Dual licensed under LGPL 2.0+ and MIT.
+
+## Thanks ##
+
+The form of this README was inspired by [Nadia Odunayo][hospitable] on
+the Greater Than Code podcast.
+
+[havocp]: https://blog.ometer.com/2008/08/25/embeddable-languages/
+[gscript]: https://gitlab.gnome.org/Archive/gscript/tree/master/gscript
+[litl webbook]: https://en.wikipedia.org/wiki/Litl
+[GNOME Shell]: https://wiki.gnome.org/Projects/GnomeShell
+[treitter]: https://treitter.livejournal.com/14871.html
+[eos-knowledge-lib]: http://endlessm.github.io/eos-knowledge-lib/
+[Cinnamon]: https://en.wikipedia.org/wiki/Cinnamon_(software)
+[hospitable]: http://www.greaterthancode.com/2017/11/08/054-code-hospitality-with-nadia-odunayo/