Improve documentation

[sindresorhus]

We've worked hard on making the documentation good, but we're biased as we made this thing and don't see it the way a first time users see it.

Documentation improvements of any kind are much appreciated. Anything to make things more explicit, more examples, fix grammar, anything.

[jamestalmage]

Are you open to github-pages documentation, or do you want to keep it all in the README?

http://documentation.js.org/ looks interesting. (particularly this demo)

Also, you probably want to reserve ava at https://dns.js.org/ (that would get you https://ava.js.org)

[sindresorhus]

Are you open to github-pages documentation, or do you want to keep it all in the README?

I would prefer to keep it in the readme for now. I plan on having a website for AVA, but not until after 1.0.0. I want to focus on AVA itself for now. Marketing can be prioritized later.

http://documentation.js.org/ looks interesting. (particularly this demo)

Indeed. There's also https://readme.io/ (free for open-source).

Also, you probably want to reserve ava at https://dns.js.org/ (that would get you https://ava.js.org)

I already have https://ava.li.

[jamestalmage]

Wow, documentation.js produces really nice output.

Even the base output is pretty slick. Each method has a link to the source on GitHub (that works really well). Base types automatically link to developer.mozilla.org

[jamestalmage]

Another plus for generation API docs using some JSDoc based system is that it improves typing hints on Webstorm significantly (I am assuming other IDE's as well).

[sindresorhus]

Agreed, documentation.js looks really good.

Not a big fan of JSDoc. If I wanted type-hints I would go with Facebook Flow.

[sindresorhus]

@jamestalmage I opened a separate issue for a future website: #162

[jamestalmage]

The documentation should cover how to get AVA working with production code.

There is a lot of confusion #111

It should incorporate the code from this comment.

It gets the point across pretty quick

[sotojuan]

I said this on Gitter but putting it out here for further discussion:

In the async function support section, I think a short explanation of what async/await functions could be helpful for newbies. We could add something about how they make asynchronous code look synchronous. Perhaps add one more "real world" example to the examples there already? I just want people to find out about async/await and not just gloss over the section!

Also willing to help with commenting functions for documentationjs.

[sindresorhus]

@sotojuan I'm all for that, but would prefer to keep it succinct and rather link to a good blog post or two with more comprehensive explanation.

[sindresorhus]

We're now also looking for people interested in translating the docs: https://github.com/sindresorhus/ava-docs