Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation #160

Closed
sindresorhus opened this issue Nov 8, 2015 · 10 comments
Closed

Improve documentation #160

sindresorhus opened this issue Nov 8, 2015 · 10 comments

Comments

@sindresorhus
Copy link
Member

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
Copy link
Contributor

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
Copy link
Member Author

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Member Author

Agreed, documentation.js looks really good.

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

@sindresorhus
Copy link
Member Author

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

@jamestalmage
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Member Author

@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
Copy link
Member Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants