First stab at the documentation.

README.md

@@ -1,3 +1,101 @@
-# npm-testing
+# LJSTHW Bandolier
 
-This is only for testing npm init for installing other things.
+The Bandolier is an educational web framework featured in the [Learn JavaScript the Hard Way](https://learnjsthehardway.com) course.  The Bandolier contains all of the features a full stack developer would need to learn, but with smaller easier to understand implementations that are fully visible in the project.
+
+This repository contains an installer tool that creates Bandolier projects for you.  It downloads the code for a basic Bandolier web application using a template repository and configures it for you.  It will also provide additional management features in the future to help you while you take the course.
+
+## Installation
+
+You simply use `npm` to install directly from the git repository:
+
+```shell
+npm install git+https://git.learnjsthehardway.com/learn-javascript-the-hard-way/ljsthw-bandolier.git
+```
+
+Once it's installed you can list your packages to confirm you installed the correct one:
+
+```
+npm list
+```
+
+## Usage
+
+You now have an `npx` command named `bando-up` which lets you create start your projects:
+
+```
+npx bando-up version
+npx bando-up --help
+```
+
+This will print the version and list all of the available commands, with the most important being create:
+
+```
+npx bando-up create my-first-project
+```
+
+This will create an initial web application using the course's web framework named `Bandolier`.  It checks out the project from the `git.learnjsthehardway.com` site and then configures it so you get started.
+
+## Updating
+
+When there's new releases you can update with:
+
+```
+npm update ljsthw-bandolier
+```
+
+That should download any new versions, but if it doesn't then it's safe to remove the project and reinstall it:
+
+```
+npm remove ljsthw-bandolier
+npm install git+https://git.learnjsthehardway.com/learn-javascript-the-hard-way/ljsthw-bandolier.git
+```
+
+## Removing
+
+As mentioned before, you can remove the project with:
+
+```
+npm remove ljsthw-bandolier
+```
+
+## Getting the Code
+
+If you want to see how this code works (please do), then you can check it out with `git`:
+
+```
+git clone https://git.learnjsthehardway.com/learn-javascript-the-hard-way/ljsthw-bandolier.git
+```
+
+# FAQ
+
+Some answers to questions I'm sure I'll receive.
+
+## Why Not an npm Module?
+
+The Bandolier is designed for _you_ to change it.  You are expected to study the code, change it how you want, and learn how everything is made.  Every component in The Bandolier is small, and not feature complete _on purpose_, as that gives you room to experiment.  Placing the code directly in your own project gives you easy access, and _permission_ to make changes and see how it works.
+
+There's a psychological and technical deterrent to changing code in `node_modules`.  There's nothing preventing you from going into `node_modules` to change the code. I do it all the time when I'm debugging, but something about it makes you feel "dirty" because it seems like it's owned by someone else.  Moving the code out of `node_modules` makes it clear _you_ can view it and change it.
+
+The technical deterrent to changing code in `node_modules` comes from the complex ecosystem behind `npm`.  If you make changes then how can you maintain them?  You'd need to create forks of the original, submit pull requests, submit bug reports, wait for the original author to finalize the change, or create your own npmjs.com registration of your fork.  All of that is valuable to learn, but it's far too much work for someone who just wants to experiment while they're learning.
+
+The `ljsthw-bandolier` project simplifies exploration by placing the code right there in your project.  Enjoy.
+
+## Isn't That Unsafe?
+
+If you think modules on npmjs.com are magically "safe" because it's a big website owned by Microsoft then you'd be very wrong.  NPM has almost no restrictions on what can be registered and has famously allowed typo-squatters to hijack projects to distribute malware. In fact, this is so common I had to register placeholders for this project in npmjs.com just in case someone tried to typo-squat it.
+
+With `ljsthw-bandolier`, you see all of the code, and all of the changes, so you are fully informed of what will happen when you update. It's also managed on my private website at git.learnjsthehardway.com, so nobody can typo-squat it.
+
+If you think it's dangerous to let people change the code they download, then how do you expect them to learn how that code works? Letting people make mistakes and break things isn't dangerous in an educational setting.  It's how they learn to not break things in the real world.
+
+## Doesn't That Make Updates Difficult?
+
+_Yes._  This is the major problem with this style of project creation.  If you installed a module using `npm` then you could easily download updates with a few commands.  Assuming the update doesn't require changes in your code you'd be done.
+
+When the code is exported into your project it becomes much more difficult to update.  If there's updates to code you don't change then simple patches will work, but if you've modified files then you'll have to study the changes and apply them yourself.  Manually doing updates _can_ be educational, but it's definitely not optimal in a real world situation.
+
+In the future this tool will have commands to help with updating your code, but the first release doesn't support that.
+
+## Why Not github?
+
+I don't want to give any more of my [property to Microsoft](https://www.saverilawfirm.com/our-cases/github-copilot-intellectual-property-litigation). They've proven they're not friends of Open Source, and any code placed on their websites will end up in their automated copyright infringement tools.