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

2.0 Docs #319

Closed
chrisvfritz opened this Issue Jun 17, 2016 · 70 comments

Comments

@chrisvfritz
Member

chrisvfritz commented Jun 17, 2016

Guidelines for writing official Vue docs

These are not immutable dictates, but rather a place to consolidate our evolving consensus. If there's an item you strongly disagree with, please do discuss it below and this section will be updated to better explain and reflect the new consensus.

  • Use 2-space indentation in examples for all languages.
  • Use only ES5 features in JavaScript examples unless the example already requires a build process or demonstrates a plugin that is almost exclusively used in applications complex enough to warrant a build process (e.g. vuex or vue-router).
  • Adhere to ferross/standard in JavaScript examples.
  • Adhere to Google's style guide for HTML and CSS. You probably don't have to actually read it, because wildly diverging styles are less common in these languages, but this resource can be used to end bikeshedding.
  • Use el: '#app' in place of el: 'body' to encourage the thinking that you are able to limit Vue's scope on your page.
  • Use JSFiddle exclusively for embedded and linked demos. The only exception is WebpackBin may be used to demonstrate code that requires a build step, such as the .vue file syntax or JSX.
  • Use https://unpkg.com/vue@next/dist/vue.js to reference Vue 2.0 in all fiddles.
  • Use CDN links with hardcoded versions to reference companion libraries.
  • Reference linked resources that do not yet exist with !!TODO: ... in place of the URL. The !! prefix makes them distinguishable from todo list examples in a search. 😛
  • When referencing the library, use Vue.js in page titles and Vue for every subsequent mention.
  • When referencing companion libraries, use the name on GitHub and NPM (e.g. vue-router rather than Vue Router or VueRouter).
### Contributing 1. Edit this comment to change `unclaimed` to `@Yourusername` so everyone knows you're working on a file. 2. Commit directly to the `2.0` branch 3. Try to edit only one file (the one you claimed) at a time. 4. When ready to push, `git fetch origin 2.0`, `git rebase origin/2.0`, then `git push origin 2.0`. (Yes, we're skipping code review for now. Let's just get something in place for this first pass.) 5. Update this comment to put a check next to the file you updated. ### Guide Updates

This list is incomplete and only represents the first pass we'll make in rewriting the docs for 2.0. It's very likely we'll want to remove/add/reorganize many pages and sections. As more issues become apparent in the process of writing docs, we can discuss them here in this issue.

Misc topics that need better coverage

  • @chrisvfritz v-once
  • @chrisvfritz how to do <script type="text/x-template" id="foo"> with template: '#foo'
  • v-cloak not very frequently used, so probably fine to just be in API doc
  • v-pre not very frequently used, so probably fine to just be in API doc
  • @chrisvfritz ref in non-v-for contexts?
### API Updates

Resources:

Sections:

  • @fadymak Global Config
  • @fadymak Global API
  • Instance Options
    • @fadymak Data
    • @fadymak DOM
    • @fadymak Lifecycle Hooks
    • @fadymak Assets
    • @fadymak Misc
  • @kazupon Instance Properties
  • Instance Methods
    • @kazupon Data
    • @kazupon Events
    • @kazupon DOM
    • @kazupon Lifecycle
  • @kazupon Directives
  • @kazupon Special Elements
  • @yyx990803 Special Attributes
  • unclaimed VNode just point to vnode source
  • unclaimed Server-Side Rendering just point to GitHub

@yyx990803 yyx990803 referenced this issue Jun 17, 2016

Closed

Docs #3092

9 of 9 tasks complete
@yyx990803

This comment has been minimized.

Member

yyx990803 commented Jun 18, 2016

Re using el: body: let's keep them to ids. I want to encourage the thinking that you are able to limit Vue's scope on your page.

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jun 18, 2016

@yyx990803 👍 Updated the guidelines.

@zigomir

This comment has been minimized.

Contributor

zigomir commented Jun 19, 2016

I went over 2. Overview I think everything still holds for Vue 2.0. Examples work fine. One thing I'm not really sure is if Vue 2.0 is also supporting IE9 and above? If that's true then we might not need to change anything in overview.md file.

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jun 19, 2016

@zigomir I just went through the Overview section and mostly just added more links, but it did indeed need very little change. 😃

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jun 19, 2016

@yyx990803 In writing some documentation for lifecycle hooks, it occurred to me that all of them are in pairs (e.g. beforeMount/mounted and beforeDestroy/destroyed), except for init and created. What would you think about renaming init to beforeCreate for consistency? That may also make it more obvious that at this stage, nothing has actually been initialized.

@zkwolf

This comment has been minimized.

zkwolf commented Jun 21, 2016

In computed.md line 72, it should be vm.message = 'Goodbye'

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jun 21, 2016

@zkwolf Thanks!! Good catch. 😄 Just fixed it.

@zkwolf

This comment has been minimized.

zkwolf commented Jun 21, 2016

@chrisvfritz And ... In list.md Object v-for section, you forget change val to value

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jun 21, 2016

@zkwolf Woohoo! Fixed. 😃 Thanks again for your excellent eye.

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jun 22, 2016

@yyx990803 Is there a way to add new keyCode aliases in 2.0? The only gettable directives seem to be model and show.

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jun 22, 2016

@yyx990803 Also, it looks like transition no longer applies a -transition class. I didn't see this explicitly listed as a planned deprecation, so double checking. Should users just add their own always-on class if they want one?

@yyx990803

This comment has been minimized.

Member

yyx990803 commented Jun 22, 2016

@chrisvfritz yeah, overlooked the custom keyCodes usage. Implemented in vuejs/vue@4fe51a7. It is now exposed as Vue.config.keyCodes.

Yes, transition no longer applies the automatic class. The user can either provide the always-on class themselves, or define the transition property in enter-active/leave-active classes.

@MeiYuanChen

This comment has been minimized.

MeiYuanChen commented Jun 23, 2016

1.vue-server-renderer can solve 'seo' question?
2.Why not ’Guidelines Vue docs‘ inside vue-server-renderer?

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jun 23, 2016

@MeiYuanChen Moving all the docs into a Vue app would take a lot of time to port and the advantages wouldn't be that significant at this point. Hexo is working for us just fine for now. 😃

@zkwolf

This comment has been minimized.

zkwolf commented Jun 27, 2016

In forms.md line185, it should be <span>Selected: {{ selected }}</span>

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jun 28, 2016

@zkwolf Another excellent catch! Fixed.

@cezaraugusto

This comment has been minimized.

cezaraugusto commented Jul 4, 2016

Hi Vue team, two questions:

  1. Are those docs open for outside contributors? If so, is the above steps mentioned by @chrisvfritz enough to contribute? Is there something else?
  2. If I plan to translate the current documentation: would it be better to wait until 2.0? Is it a breaking version or just improvements? Which things should I be aware of?

Regards

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jul 4, 2016

Hi @cezaraugusto! Great questions. 😃

  1. Feedback is definitely welcome, but major contributions from outside the core team won't be practical until the first draft rewrites have all been done. The reason is that a lot of internal discussions are fueling the rewrite, which then often lead to API changes, which then lead to more rewrites. 😜 For the docs that already have a check mark next to them, the first draft has been completed and @zkwolf and others have already found a lot of room for improvement. If you also want to look them over, we'd love to hear your thoughts.
  2. For translation, I would probably wait until Vue reaches at least the RC stage, when the API will be very stable and the source documentation will be much less likely to drastically change.

Let me know if that fully addresses your questions.

@cezaraugusto

This comment has been minimized.

cezaraugusto commented Jul 4, 2016

Sure @chrisvfritz, thanks for clarifying. Great job so far 👌 , am following closely 👀 .

@kazupon kazupon self-assigned this Jul 6, 2016

@theotherzach

This comment has been minimized.

theotherzach commented Jul 9, 2016

Use only ES5 features in JavaScript examples unless the example already requires a build process or demonstrates a plugin that is almost exclusively used in applications complex enough to warrant a build process (e.g. vuex or vue-router).

Thank you so, so, so, so, so, so, so, so, so, so, so, SO very much for this. I teach Vue to people as an introduction to frontend JavaScript, often in programming communities with little to no culture of JS tooling, so this is huge for me. Thank you thank you thank you thank you thank you.

@LinusBorg LinusBorg referenced this issue Jul 18, 2016

Closed

2.0 Changes #2873

105 of 105 tasks complete
@miljan-aleksic

This comment has been minimized.

Contributor

miljan-aleksic commented Jul 18, 2016

@chrisvfritz, should I open a ticket about issues I found or comment them here first?

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Jul 18, 2016

@miljan-aleksic You can just comment here. Thanks for your help!

@FadyMak FadyMak self-assigned this Aug 4, 2016

@dan-gamble

This comment has been minimized.

dan-gamble commented Aug 5, 2016

All i can say after cloning and running this is wow! Absolutely awesome job on the new docs and Vue 2 overall and i've only read the new transition page so far..

@blocka

This comment has been minimized.

blocka commented Aug 7, 2016

I would like to point out two things in comparison docs...I hope this is right place for this.
The first is the claim that "React has made strides in this area, but has yet to produce a production-ready, out-of-the-box solution for new projects." Actually, react as something like this, called "create-react-app", which is certainly production ready. Perhaps there should be a comparison between vue-cli and create-react-app?

The second is the issue with if statements vs ternary statements in jsx. While this is definitely an issue, there is a solution on the horizon, in the form of do expressions. With do expressions, a if/else can be wrapped into one expression and used in JSX (or in array functions for that matter), which makes the syntax a tiny bit more palatable.

For example:

<div className='myComponent'>
    {do {
      if(color === 'blue') { <BlueComponent/>; }
      if(color === 'red') { <RedComponent/>; }
      if(color === 'green') { <GreenComponent/>; }
    }}
  </div>

There is still "syntax tax", but it's definitely nicer looking then hoisting or using ternaries.

chrisvfritz referenced this issue Aug 7, 2016

Maintain js code highlighting.
Wrap because class is JS reserved keyword.
@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Aug 7, 2016

@blocka Thanks for taking a look at this! The comparisons section is definitely something the team will be discussing in more detail before the final release. Regarding those specific items:

Production use of create-react-app

We're aware of this project, but even their documentation only recommends it for getting started with React. It's currently missing many features vital for non-trivial projects, most notably the lack of support for any testing, CSS preprocessors, ES7/2016 features such as the object spread operator and decorators (both are often used quite extensively within React projects), and hot module reloading.

If I were starting a new React project today, I can't think of a scenario where I would use it - and even if I were forced to, I'd have to immediately eject and modify the build process before any significant work could begin.

I think adding a note to let people know we are aware of this project would be good though. 👍

Do expressions for cleaner JSX

I'm definitely excited about do expressions. They'll help a little, but they're currently at stage 0, which is a little more unstable than many projects are willing to work with at this point. I'll add a note about them nonetheless.

@gaearon

This comment has been minimized.

Contributor

gaearon commented Aug 8, 2016

We're aware of this project, but even their documentation only recommends it for getting started with React.

This is not the case. It is explicitly labeled “production-ready”. Yes, it is currently catered more to beginners than to advanced users, but even advanced users find it useful:

screen shot 2016-08-08 at 13 40 02

screen shot 2016-08-08 at 13 40 10

(This is from the post-eject survey.)

It's currently missing many features vital for non-trivial projects, most notably the lack of support for

any testing

The support for testing has been merged, and while we may tweak a few things before releasing it officially, it is going to be added. I believe README explicitly says we intend to add testing.

CSS preprocessors

You can run your existing preprocessors just fine if you want to, and import resulting css files. We don’t intend them to be part of the default setup but they’re perfectly usable from create-react-app, with the same workflow that people have been using for years.

ES7/2016 features such as the object spread operator

This is incorrect, spread operator has been supported from the very first release.

and decorators (both are often used quite extensively within React projects)

Decorators are currently not officially supported by Babel, have weird hard-to-diagnose issues, and the spec is still changing. In my experience many people get confused by decorators, and I’m not comfortable including them while they are so unstable in practice.

and hot module reloading.

It’s enabled for CSS, but hot reloading for React components is currently too flaky. (I hope I qualify to speak about that 😄 .)

We care about providing the complete cohesive experience, not just picking the latest popular things. So yes, we leave something out, but we do it on purpose, and not because the tool is half-baked.

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Aug 8, 2016

Thanks for the input @gaearon! This is definitely helpful in making sure we don't misrepresent the create-react-app project. 😃 Some quick notes:

  • Object Spread Operator: The support for the object spread operator was definitely a misreading on my part - I apologize for that.
  • CSS Preprocessors: I would personally prefer not to maintain multiple parallel build systems, but I can see your point that it is possible.
  • Production-Ready vs Development-Ready: I did see that it's ready for production and I don't dispute that. The question for me was more whether it was development-ready. With some of the missing features, it wouldn't (currently) be possible for me to generate a new client project and start coding right away, like I can with vue-cli's Webpack template. I'd have to first eject and spend considerable time enhancing the build process and development environment. The addition of out-of-the-box testing goes most of the way in resolving this though, so I'll write assuming it'll be included by the time these docs are released.

Project Goals

I think this is a misconception that could be resolved by updates to the README. My understanding that it was mainly intended for onboarding came from the "Why Use This?" section, which starts with "If you’re getting started with React [...]" - the bolding is not mine.

Testing Support

Glad to hear that it's on the way!

believe README explicitly says we intend to add testing.

I didn't see any explicit mention of this. The section I think you may be referring to contains 3 qualifiers (italics are mine):

Some of them might get added in the future if they are stable, are useful to majority of React apps, don't conflict with existing tools, and don't introduce additional configuration.

This doesn't convey a sense of inevitability to me, but a tweaking to the wording in the first clause might be helpful if you wish to - something like: "We're actively working on the features above and they will be added when [...]".

Thanks Again 😄

Thanks again for the feedback! As we revise this section a little more, I'll be sure to mention/tweet you so you can take another look.

@gaearon

This comment has been minimized.

Contributor

gaearon commented Aug 8, 2016

Thanks for the feedback. We’ll tweak messaging as we get to 1.0 and make this thing more official.

@posva posva referenced this issue Aug 16, 2016

Closed

vue-router 2.0 Docs #616

34 of 47 tasks complete
@RVya

This comment has been minimized.

RVya commented Aug 23, 2016

Good,Good,But Where is The Chinese Docs ? ? ? @yyx990803

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Aug 24, 2016

@AyAmeng As far as I know, translation to Chinese hasn't started yet. When it does, would you like to help?

@smithb1994

This comment has been minimized.

smithb1994 commented Aug 25, 2016

At https://rc.vuejs.org/guide/components.html#Form-Input-Components-using-Custom-Events please consider rewriting the last example from:

template: '\
    <div class="form-group">\
      <label v-bind:for="randomId">{{ label }}:</label>\
      <input v-bind:id="randomId" v-bind:value="value" v-on:input="onInput">\
    </div>\
  '

and change it to a more readable:

template:
    '<div class="form-group">' +
      '<label v-bind:for="randomId">{{ label }}:</label>' +
      '<input v-bind:id="randomId" v-bind:value="value" v-on:input="onInput">' +
    '</div>'

Thanks

@blocka

This comment has been minimized.

blocka commented Aug 25, 2016

Even better

template:
    `<div class="form-group">
      <label v-bind:for="randomId">{{ label }}:</label>
      <input v-bind:id="randomId" v-bind:value="value" v-on:input="onInput">
    </div>`

unless for some reason es6 is avoided in the docs.

@smithb1994

This comment has been minimized.

smithb1994 commented Aug 25, 2016

Similar template readability complaint at https://rc.vuejs.org/guide/components.html#Components-and-v-for

@smithb1994

This comment has been minimized.

smithb1994 commented Aug 25, 2016

At https://rc.vuejs.org/guide/components.html#Async-Components do components accept a returned promise? It didn't indicate whether it did.

@smithb1994

This comment has been minimized.

smithb1994 commented Aug 25, 2016

@LinusBorg

This comment has been minimized.

Member

LinusBorg commented Aug 25, 2016

@blocka: we use ES5 in the guide (See the second bullet point in the OP), so no template strings.

@smithb1994 Personally, I don't think your way of writing the template is nessessarily more readable, but we will see how he others feel about it.

@smithb1994

This comment has been minimized.

smithb1994 commented Aug 25, 2016

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Aug 25, 2016

@smithb1994

  • Template style: It sounds like just a matter of preference (and your version actually has more syntax characters), so we won't be changing it for now.
  • Lifecycle diagram: We are aware. These docs are work-in-progress and if you look at the src for the missing image, you'll actually see !!TODO: EVAN WILL NEED TO UPDATE /images/lifecycle.png. 😉
  • Promises with Async Components: You cannot return a promise in async components. The described interface is the only one available. You can still easily use a promise like this though. Edit: Evan just added this feature to rc4. 😃

@zigomir zigomir removed their assignment Aug 27, 2016

@chay22

This comment has been minimized.

chay22 commented Sep 5, 2016

Few lines under here (on list) tells slots as in context, contains slot object while I have to call it as a function first to get the object returned. Am I missing something?

Also for the lack of directives in #render() is good to mention, too. Something like, here on the second line of first paragraph.

For example, the lack of use of Vue built-in directives in render functions forv-if and v-for as in template:

@hasssan

This comment has been minimized.

hasssan commented Sep 6, 2016

Incorrect command in Guide: Coditional and Loops section:

"In the console, enter app3.todos.push({ text: 'New item' })"
should be:
"In the console, enter app4.todos.push({ text: 'New item' })"

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Sep 7, 2016

@chay22 You're not missing anything - slots is indeed a function that returns a slots object within functional components. The docs have now been updated to reflect that. As for the directives, it's not universally true no directives are allowed in render functions. For example, v-on has the on equivalent. It's really only when for directives or other Vue features that can be easily replaced with simple JavaScript.

@hasssan Thanks! Fixed the typo.

@jbruni

This comment has been minimized.

Contributor

jbruni commented Sep 16, 2016

@chrisvfritz @yyx990803

vm.$el documentation at https://github.com/vuejs/vuejs.org/blob/2.0/src/api/index.md#vmel

currently says

The DOM element that the Vue instance is managing. vm.$el will return a DOM element that created with the Vue instance.

The first sentence is ok. The second sentence needs to be rephrased.

(Sorry, I don't have a good suggestion. I would have made a PR if I had.)

Thank you.

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Sep 16, 2016

@jbruni Thanks, fixed!

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Sep 16, 2016

We're locking this thread for now, as the discussion part of the docs is pretty much done now. We still welcome continued feedback in the form of new issues though! 😃

@vuejs vuejs locked and limited conversation to collaborators Sep 16, 2016

@chrisvfritz

This comment has been minimized.

Member

chrisvfritz commented Sep 20, 2016

The core docs are now officially complete! We'll continue to improve them, but everything should have basic coverage.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.