First read-through

[Xowap]

As stated before, great to see those docs coming!

I had a first read of them and here is some feedback. Overall the doc is very clear and straightforward, yet a few things could be improved. A lot of those comments assume your target an audiance new to VueJS and might not be so relevant but I'll let you guys judge of that.

Installation

• The install process works as-is, which is pretty great since it's far to always be the case

Directory structure

• It says "Nuxt.js doesn't require a lot of directory structure convention. It is free to define most of the directory structure with its own convention." but I guess what it means is "Nuxt.js doesn't require a lot of directory structure convention. You are free to define most of the directory structure with your own convention."
• In the suggested structure, directory names are just standing there but it'd be interesting to know what is the intended purpose of each directory
• There is a whole section on aliases, but:
  • Isn't webpack doing those automatically? If you put a /foo directory you automatically get the ~foo alias right?
  • It'd be interesting to explain the point of it, because users not knowing webpack might not realize what's the use/power of that

General comments

• Maybe an overview of how the whole thing is bundled would be nice. There's at least webpack, vue, vue-router, vuex, vue-loader to explain
• It would be pretty usefull to get something on why SSR, the pitfalls and gotchas of it with links to relevant parts of the doc
• Webpack looks like dark magic to most people. Some pedagogy would be interesting on that side (nothing huge, just a nice well-explained drawing and pointers to relevant resources)

Contribution guide

• You could suggest a contribution template, especially for bug reports
• You could also explain the issue workflow: what kind of issues you want to see, what kind of feedback you expect, ... I've been posting some issues and have been uneasy on how to write them and if I should write them at all (like this one)

Routing

• You do not explain how to do something like /post/42 to display a specific post with an ID from the URL. I don't think this goes into "advanced" routing as you're going to need to do that in almost any app you're going to write
• What is the point of hidden pages? I fear an anti-pattern here and I think that the reason behind this should at least be explained

Async data

• Although the grammar of "data" is highly controversial, one thing is for sure: "data" never gets an "s". You might want to fix the title.
• Related to this issue I opened, I think you might want to find out at least one pattern and explain it well in the page

[alexchopin]

Hi, thanks so much for your precious feedback.
The documentation is important for us and we really try to find a way to explain Nuxt with the easiest sentences possible, but it's hard ;)

[Xowap]

I know how you feel! Happy to help :)

[atinux]

Hi @Xowap

To keep you updated, since the 0.9.0, there is no more hidden files, see https://github.com/nuxt/nuxt.js/tree/master/examples/custom-routes#dynamic-routes

[Xowap]

Excellent!