add registry info and refactor publish page

1 files changed, 39 insertions, 39 deletions

diff --git a/docs/cookbook/publish.md b/docs/cookbook/publish.md
index fa61304..2dd5baa 100644
--- a/docs/cookbook/publish.md
+++ b/docs/cookbook/publish.md
@@ -2,43 +2,8 @@
 
 Dat has privacy by default, but what if you want to share your dat with the world publicly, or within your organization? There are a variety of ways to do this, which we describe here.
 
-## Dat Registry
-
-We have built a web server that allows you to create a user account and build your list of datasets, giving them names, titles, and descriptions that make it easy to share your data with the general public. The registry does not take care of long-term hosting of your data -- the registry only acts as a way to easily surface available dats in a searchable list. A dat registry is similar to a torrent tracker, if you're familiar with those.
-
-We have hosted a global public registry at [https://datproject.org](https://datproject.org). First, you must create an account:
-
-```
-$ dat register
-Welcome to dat program!
-Create a new account with a Dat registry.
-
-Dat registry:  (datproject.org)
-```
-
-By default, `dat` will use `datproject.org` as the registry. If you'd like to host your own registry, you can type in your own server name here.
-
-Now, you can `dat login` with the account you just made.
-
-Finally, use `dat publish` to publish the dat in the current folder. Make sure you've already created a dat using `dat create` or `dat share`
-
-`dat publish` will ask you for a name for your dat. This is the short name that will be part of the URL, for example:
-```
-cd /path/to/my/dat
-$ dat publish
-Name: more-tweets-more-votes
-Published successfully!
-```
-
-Once the dat is published, you can visit it. For this example: [https://datproject.org/karissa/more-tweets-more-votes](https://datproject.org/karissa/more-tweets-more-votes).
-
-In order for anyone to see the dat, you'll need to have `dat share` running on your current dat. If you want to turn off your desktop, we recommend setting up a server to host your dats.
-
-[Learn how to set up a long-term server for hosting dats](/server)
-
-## Using Git with `dat.json`
-
-If you're familiar with git, you might want to be able to get the collaborative benefits of git along with the benefits of fast data download, versioning, p2p, and deduplication with dat. To do this, you want to create a `dat.json` file in your Git repository. The `dat create` command does this for you.
+## Create dat.json file
+When referencing your dat, you want to be able to have some way to specify what the dat is -- like a title, description, and url. To do this, we recommend creating a `dat.json` file as well as a README in your dat archive. The `dat create` command creates a `dat.json` file for you by default:
 
 ```
 $ dat create
@@ -69,6 +34,41 @@ This will generate a `dat.json` file which you can use to reference your dat in
 }
 ```
 
-To save space in your git repo, you can then add `.dat` to your `.gitignore` file in your git repository to make sure none of the metadata makes it in there.
+Dat can read these files to know how to download and catalogue your dat. This is the most simple version, but they can get more complicated if you want. You can use this file in other applications such as a registry, data portal, or git repository to reference your dat.
+
+## Dat Registry
+
+We have built a web server that allows you to create a user account and build your list of datasets, using the dat.json file to give them names, titles, and descriptions that make it easy to share your data with the general public. The registry does not take care of long-term hosting of your data -- the registry only acts as a way to easily surface available dats in a searchable list. A dat registry is similar to a torrent tracker, if you're familiar with those.
+
+We have hosted a global public registry at [https://datproject.org](https://datproject.org). First, you must create an account:
+
+```bash
+$ dat register
+Welcome to dat program!
+Create a new account with a Dat registry.
+
+Dat registry:  (datproject.org)
+```
+
+By default, `dat` will use `datproject.org` as the registry. If you'd like to host your own registry, you can type in your own server name. Once you have an account, you can use `dat publish` to publish your dat to the registry.
+
+First, `dat publish` will ask you for a name for your dat. This is the short name that will be part of the URL, for example, more-tweets-more-votes would be `myusername/more-tweets-more-votes`:
+
+```bash
+cd /path/to/my/dat
+$ dat publish
+Name: more-tweets-more-votes
+Published successfully!
+```
+
+Once the dat is published, you can visit it. For this example: [https://datproject.org/karissa/more-tweets-more-votes](https://datproject.org/karissa/more-tweets-more-votes).
+
+In order for anyone to see the dat, you'll need to have `dat share` running on your current dat. If you want to turn off your desktop, we recommend setting up a server to host your dats.
+
+[Learn how to set up a long-term server for hosting dats](/server)
+
+## Using Git with `dat.json`
+
+You might want to be able to get the collaborative benefits of git along with the benefits of fast data download, versioning, p2p, and deduplication with dat. All you have to do is include the `dat.json` file in your git repository, and tell people to type `dat clone` for them to get the latest version of your data. Now, when someone clones your git repository, they can download your data by simply typing `dat clone dat.json`, and the url in the dat.json will be used to download the dat.
 
-Now, when someone clones your git repository, they can download your data by simply typing `dat clone dat.json`, and the url in the dat.json will be used to download the dat.
+To save space in your git repo, you probably want to add `.dat` to your `.gitignore` file in your git repository to make sure none of dat's metadata is included. Dat by default ignores your `.git` folder, so you don't have to worry about that.