feedback regarding new user onboarding about data

[btc]

like to have:

example of Datafile workflow

[jbenet]

Added some quick-start doc that attempts to explain things in jbenet/datadex@8b3584b

Check it out: http://datadex.io/doc
Linked from front-page too: http://datadex.io
Thoughts @brianholderchow ?

[btc]

This is a step in a helpful direction. This new documentation does a swell job of explaining what data needs from me and what I need to do to communicate with it.

However, there may be value in playing with voice. For example, GitHub's guides always explain why a tool needs a piece of information and why the user must enter a particular command. It's a subtle consideration that may help visitors grok more quickly.

See: https://help.github.com/articles/set-up-git

Git saves your email address into the commits you make.
We use the email address to associate your commits with your GitHub account.

$ git config --global user.email "[email protected]"
# Sets the default email for git to use when you commit

[btc]

Here is my proposal for a minimal quick start guide. It adds incremental changes to the docs you've provided by attempting to examplify and simplify:

https://github.com/jbenet/datadex/blob/feat/docs-quick-start/web/md/doc_quick-start.md

• Since I haven't had a chance to dogfood Datafiles, these proposed changes do not address Datafiles.
• I believe there's a place for both short form and long form instructions. For a new user, there is considerable benefit to separating them to reduce noise.

[jbenet]

Thanks! that's much cleaner. I'll put my longer explanations lower in the file. Think it worth splitting into two pages? Docs > Quick Start and Docs?

[btc]

Noise reduction is such an important part of a useful quick start guide, I really believe quick start is best on its own page

On Sat, Feb 8, 2014 at 6:23 PM, Juan Batiz-Benet [email protected]
wrote:

Thanks! that's much cleaner. I'll put my longer explanations lower in the file. Think it worth splitting into two pages? Docs > Quick Start and Docs?

Reply to this email directly or view it on GitHub:
#17 (comment)

[btc]

The links could take users to comprehensive documentation. On the comprehensive documentation, there would be no need for brevity.

On Sat, Feb 8, 2014 at 6:26 PM, Brian Holder-Chow Lin On
[email protected] wrote:

Noise reduction is such an important part of a useful quick start guide, I really believe quick start is best on its own page
On Sat, Feb 8, 2014 at 6:23 PM, Juan Batiz-Benet [email protected]
wrote:

Thanks! that's much cleaner. I'll put my longer explanations lower in the file. Think it worth splitting into two pages? Docs > Quick Start and Docs?

Reply to this email directly or view it on GitHub:
#17 (comment)

[jbenet]

Ok, i merged it in jbenet/datadex@c329f24. (I rebased to squash some of the commits).

[jbenet]

Deployed. Live at http://datadex.io/doc/quick-start