Cleanup readme and docs for using docs.dat-data.com

README.md

@@ -1,54 +1,105 @@
-# dat
+# Dat
 
 Dat is a decentralized data tool for distributing data small and large.
 
 [![#dat IRC channel on freenode](https://img.shields.io/badge/irc%20channel-%23dat%20on%20freenode-blue.svg)](http://webchat.freenode.net/?channels=dat)
 [![datproject/discussions](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/datproject/discussions?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![docs](https://readthedocs.org/projects/dat-cli/badge/?version=latest)](http://docs.dat-data.com)
-
-
-Windows        | Mac/Linux
--------------- | ------------
-[![Build status](https://ci.appveyor.com/api/projects/status/github/maxogden/dat?branch=master&svg=true)](https://ci.appveyor.com/project/maxogden/dat) | [![Travis](https://api.travis-ci.org/maxogden/dat.svg)](https://travis-ci.org/maxogden/dat)
-
-## About Dat
-
-Documentation for the Dat project is available at [docs.dat-data.com](http://docs.dat-data.com).
+[![docs](https://img.shields.io/badge/Dat%20Project-Docs-green.svg)](http://docs.dat-data.com)
 
 ### Key features:
 
-  * **Live sync** folders by sharing files as they are added to the folder.
+  * **Live sync** folders by sharing files as they are added or changed.
   * **Distribute large files** without copying data to a central server by connecting directly to peers.
   * **Intelligently sync** by deduplicating data between versions.
   * **Verify data integrity** using strong cryptographic hashes.
-  * **Work everywhere**, including in the [browser](https://github.com/datproject/dat.land) and on the [desktop](https://github.com/juliangruber/dat-desktop).
+  * **Work everywhere**, including on the [command line](https://github.com/datproject/dat), in the [browser](https://github.com/datproject/dat.land), and on the [desktop](https://github.com/juliangruber/dat-desktop).
 
-Dat embraces the Unix philosophy: a modular design with composable parts. All of the pieces can be replaced with alternative implementations as long as they implement the abstract API.
+### [Documentation](http://docs.dat-data.com) | [Video Demo](https://www.youtube.com/watch?v=fxKjSyCoqO4) | [Ecosystem](https://github.com/clkao/awesome-dat)
 
-## CLI Development Status
+---
 
-This is the Dat CLI 1.0 release candidate (RC2). We are actively seeking feedback & developing this release candidate. Follow [this issue](https://github.com/datproject/projects/issues/5) for the Dat CLI road map discussion and see [known RC2 issues](https://github.com/maxogden/dat/issues/486).
+## Dat Command Line Tool
 
-**Please note** that previous versions of Dat (alpha, beta) are incompatible with the 1.0 release candidate.
+This guide will help you get started with the Dat command line tool. We are also developing [web](https://github.com/datproject/dat.land) and [desktop](https://github.com/juliangruber/dat-desktop) applications for Dat.
+
+### Table of Contents
+
+<li><a href="#getting-started">Getting Started</a></li>
+<li><a href="#using-dat">Using Dat</a></li>
+<li><a href="#troubleshooting">Troubleshooting</a></li>
+<li><a href="#for-developers">For Developers</a></li>
+
+## Getting Started
+
+The Dat command line tool can be used to share, download, and sync files across many computers via the command line.
+
+Windows        | Mac/Linux    | Version
+-------------- | ------------ | ------------
+[![Build status](https://ci.appveyor.com/api/projects/status/github/datproject/dat?branch=master&svg=true)](https://ci.appveyor.com/project/datproject/dat) | [![Travis](https://api.travis-ci.org/datproject/dat.svg)](https://travis-ci.org/datproject/dat) | [![NPM version](https://img.shields.io/npm/v/dat.svg?style=flat-square)](https://npmjs.org/package/dat)
+
+### Installation
 
-## Getting started
+```
+npm install -g dat
+```
+
+You should be able to run the `dat` command now. If not, see the [installation troubleshooting](#troubleshooting) for tips.
+
+### Demo
+
+We have Dat installed, now let's use it! In this quick demo we will download our documentation files using Dat.
+
+You tell Dat what files to download by giving it a Dat link. Dat links are 64 character strings, for example `395e3467bb5b2fa083ee8a4a17a706c5574b740b5e1be6efd65754d4ab7328c2`.
 
-### Install
+Along with the link, you tell Dat where to download the files. All together, you can download files by typing `dat <dat-link> <download-directory>`.
 
-To install the 1.0 release candidate from npm:
+We have our Dat documentation folders being shared by Dat (at the key above). For this example, we can download those files to your computer. In your console, run:
 
 ```
-npm install dat -g
+dat 395e3467bb5b2fa083ee8a4a17a706c5574b740b5e1be6efd65754d4ab7328c2 dat_docs
 ```
 
-If you receive an `EACCES` error read [this guide](https://docs.npmjs.com/getting-started/fixing-npm-permissions).
+You should see the output below. Once the download is finished, the files will be available on your computer in the `dat_docs` folder!
+
+![Download gif](https://raw.githubusercontent.com/datproject/docs/master/assets/cli_download.gif)
+
+### CLI Development Status
+
+This is the Dat CLI 1.0 release candidate (RC2). We are actively seeking feedback & developing this release candidate. Follow [this issue](https://github.com/datproject/projects/issues/5) for the Dat CLI road map discussion and see [known RC2 issues](https://github.com/datproject/dat/issues/486).
+
+**Please note** that previous versions of Dat (alpha, beta) are incompatible with the 1.0 release candidate.
 
-### Using Dat
+## Using Dat
 
-There are two main commands in dat:
+There are two commands in Dat:
 
-1. Share data: `dat <directory>`
-2. Download data: `dat <dat-link> <download-directory>`
+1. Share data: `dat <directory>` will share a directory on your computer.
+2. Download data: `dat <dat-link> <download-directory>` will download files from the Dat link to a directory on your computer. 
+
+Running `dat` in the console, with no arguments, will show you the usage guide. You can always use this as a reference for all the commands:
+
+```
+dat <directory>
+
+  share directory and create a dat-link
+
+  --snapshot            create a snapshot of directory
+  --port, -p            set a specific inbound tcp port
+
+dat <dat-link> <directory>
+
+  download a dat-link into directory
+
+  --exit                exit process after download finishes
+  --port, -p            set a specific inbound tcp port
+
+general options
+
+  --version, -v         get installed dat version
+  --doctor              run dat doctor
+  --quiet, -q           output only dat-link, no progress information
+  --debug               show debugging output
+```
 
 ### Sharing Files
 
@@ -66,11 +117,29 @@ The Share Link is secret and only those you share it with will be able to get th
 Connected to 1 peers. Uploading 288.2 B/s. Watching for updates...
 ```
 
-You are now publishing that data from your computer. It will be publicly accessible as long as your terminal is open. The hash is a **secret hash**, your data is visible to anyone you send the hash to. As you add more files to the folder, dat will update and share the new files.
+You are now publishing that data from your computer. It will be publicly accessible as long as your terminal is open and the process is still running. The hash is a **secret hash**, your data is visible to anyone you send the hash to.
+
+#### Updating Shared Files
+
+Dat makes it easy to share a folder and send files as they are added to the folder. By default, when you share using `dat my_data/` you will be in live sync mode. Anyone connected to you will receive new files.
+
+#### Creating a snapshot
+
+A snapshot reads the files and creates a unique link that will always be the same for that set of files (if they remain unchanged). To create a snapshot use the snapshot option: `dat my_data/ --snapshot`. Snapshots are automatically created for you in live mode as files update.
+
+#### Sharing Options
+
+`dat <directory> --snapshot`
+
+Share a snapshot of the current files. 
+
+`dat <directory> --port=1234`
+
+Set your inbound TCP port. This is useful for debugging or on restrictive networks. 
 
 ### Downloading Files
 
-Your colleague can get data like this:
+Download files from a Dat link by typing: `dat <dat-link> <download-directory>`:
 
 ```
 $ dat d6e1875598fae25165eff440ffd01513197ad0db9dbb9898f2a141288b9322c6 download_dir
@@ -84,21 +153,100 @@ The Share Link is secret and only those you share it with will be able to get th
 Connected to 1 peers. Downloading 1.44 kB/s. Watching for updates...
 ```
 
-It will start downloading the data into the `download_dir` folder. Anyone who gets access to the unique dat-link will be able to download and re-host a copy of the data. It's distributed mad science!
+Dat will start downloading the data into the `download_dir` folder. Once the download is finished (a message will print and the bar will turn green), you can safely exit the process with `Ctrl-C` (`Cmd-C` on Mac). 
+
+While downloading, you may be connected to more than 1 peer. Anyone who has the Dat link will be able to download and re-host a copy of the data. So you may be downloading from (and sharing to) other people that are also downloading that data! You only need one block of data to start helping as a host. It's distributed mad science!
+
+#### Updating the Downloaded Files
+
+What happens if the files get updated? IfDat auto-syncs new files if it is still running. If you exited the process, you can run the same command you ran before (with the same link and directory) and the files will update!
+
+#### Download Options
+
+`dat <dat-link> <directory> --exit` 
+
+After files are done downloading, exit the process. If you are connected to a live Dat you will not get new files unless you run the command again.
+
+`dat <dat-link> <directory> --port=1234`
+
+Set your inbound TCP port. This is useful for debugging or on restrictive networks. 
+
+### Live Sync & Snapshots
+
+Dat makes it easy to share a folder and send files as they are changed or added. By default, when you share using Dat you will be in *live sync* mode. Anyone connected to you will receive file changes as you make them.
+
+When downloading a Dat, you do not have to worry about live mode. It will automatically start in the right mode based on the link. 
+
+To create a snapshot when sharing files use the snapshot option: `dat my_data/ --snapshot`. A snapshot reads the files and creates a specific link that will never change (as long as the files don't change).
+
+### Dat Metadata Storage
+
+When you run a command, Dat creates a hidden folder, `.dat`, in the directory specified. Similar to git, this folder stores information about your Dat. File metadata and the Dat link are stored to make it easy to continue sharing or downloading the same directory.
+
+## Troubleshooting
+
+We've provided some troubleshooting tips based on issues users have seen. Please [open an issue](https://github.com/datproject/dat/issues/new) or ask us in our [chat room](https://gitter.im/datproject/discussions) if you need help troubleshooting and it is not covered here.
+
+If you have trouble sharing/downloading in a directory with a `.dat` folder, try deleting it and running the command again.
+
+#### Check Your Dat Version
+
+Knowing the version is really helpful if you run into any bugs, and will help us troubleshoot your issue.
+
+Check your Dat version:
+
+```
+dat -v
+```
+
+You should see the Dat semantic version printed, e.g. 11.1.2.
+
+### Installation Issues
+
+#### Node & npm
+
+To use the Dat command line tool you will need to have [node and npm installed](https://docs.npmjs.com/getting-started/installing-node). Make sure those are installed correctly before installing Dat. You can check the version of each:
+
+```
+node -v
+npm -v
+```
+
+#### Global Install
+
+The `-g` option installs Dat globally allowing you to run it as a command. Make sure you installed with that option.
+
+* If you receive an `EACCES` error, read [this guide](https://docs.npmjs.com/getting-started/fixing-npm-permissions) on fixing npm permissions.
+* If you receive an `EACCES` error, you may also install dat with sudo: `sudo npm install -g dat`.
+* Have other installation issues? Let us know, you can [open an issue](https://github.com/datproject/dat/issues/new) or ask us in our [chat room](https://gitter.im/datproject/discussions).
+
+### Networking Issues
 
-For more information, see the [dat project documentation](http://docs.dat-data.com).
+Networking capabilities vary widely with each computer, network, and configuration. Whenever you run a Dat there are several steps to share or download files with peers:
 
-## Ecosystem
+1. Discovering Peers
+2. Connecting to Peers
+3. Sending & Receiving Data
 
-  * [Hyperdrive](https://github.com/mafintosh/hyperdrive): on-disk database format
-  * [Discovery Swarm](https://github.com/mafintosh/discovery-swarm): discovery mechanism
-  * [dat-js](https://github.com/joehand/dat-js): javascript library
-  * [dat-desktop](https://github.com/juliangruber/dat-desktop): desktop application
-  * [dat.land](https://github.com/datproject/dat.land): website application
+With successful use, Dat will show `Connected to 1 peer` after connection. If you never see a peer connected your network may be restricting discovery or connection. Please try using the `dat --doctor` command (see below) between the two computers not connecting. This will help troubleshoot the networks.
+
+* Dat may [have issues](https://github.com/datproject/dat/issues/503) connecting if you are using iptables.
+
+#### Dat Doctor
+
+We've included a tool to identify network issues with Dat, the Dat doctor. You will need to run the command on both the computers you are trying to share data between. On the first computer, run:
+
+```
+dat --doctor
+```
+
+The doctor will print out a command to run on the other computer, `dat --doctor=<64-character-string>`. The doctor will run through the key steps in the process of sharing data between computers to help identify the issue.
+
+---
 
 ## For Developers
 
-Please see [guidelines on contributing](https://github.com/maxogden/dat/blob/master/CONTRIBUTING.md) before submitting an issue or PR.
+Please see [guidelines on contributing](https://github.com/datproject/dat/blob/master/CONTRIBUTING.md) before submitting an issue or PR.
 
 ### Installing from source
 
@@ -110,12 +258,12 @@ npm link
 
 This should add a `dat` command line command to your PATH. Now you can run the `dat` command to try it out.
 
-The contribution guide also has more tips on our [development workflow](https://github.com/maxogden/dat/blob/master/CONTRIBUTING.md#development-workflow).
+The contribution guide also has more tips on our [development workflow](https://github.com/datproject/dat/blob/master/CONTRIBUTING.md#development-workflow).
 
 
 ### Internal API
 
-**Note: we are in the process of moving the main library to a separate module, [joehand/dat-js](https://github.com/joehand/dat-js). Temp documentation here for developers.**
+**Note: we are in the process of moving the js library to a separate module, [joehand/dat-js](https://github.com/joehand/dat-js).**
 
 #### dat.download(cb)
 
@@ -188,3 +336,7 @@ dat.appendStats = {
     dirs: 0
 }
 ```
+
+## License
+
+BSD-3-Clause