preface

Documentation, arguably one of the easiest things to do, is also one of the hardest things to do well. We’re always looking at documents, making fun of how poorly this document is written, how poorly that document is written, or, in retrospect, how poorly our own documents are written.

For Vue to be so popular, its documentation contribution is also indelible. In the open source space, there is also a core spirit of documentation first. Vue is the winner here, and it’s one of the core reasons why people love Vue and why so many developers love Vue.

So how is the Vue documentation designed? What parts are included? For our own projects, if we were to document, what could we learn from it?

This also raises the question: The Vue documentation has so many sections that if you are a heavy Vue user, have you read through the Vue documentation to understand all aspects of Vue?

The text analysis

What

The Vue documentation is available at cn.vuejs.org/index.html, of course, if you are good at English, you can access the English version at vuejs.org/index.html.

Here is the home page, and we can see the contents of the entire document:

  • Home page
  • learning
    • The document
      • The tutorial
      • API
      • Style guide
      • The sample
      • CookBook
    • Video tutorial
  • The ecological system
    • help
      • BBS
      • The chat room
      • party
    • tool
      • Devtools
      • Vue CLI
      • Vue Loader
    • The core plug-in
      • Vue Router
      • Vuex
      • Vue server render
    • information
      • weekly
      • Roadmap
      • activity
      • Twitter
      • blog
      • work
      • DEV community
  • team
  • The resource list
  • Support the Vue
  • multilingual
  • Participate in translation

It basically covers all aspects of Vue.

How

With these navigation and overview, we can’t say that the document is well written, only that it is relatively complete, and we can further pick some parts for analysis:

  • Home page
  • learning
    • The document
      • The tutorial
      • API
      • Style guide
      • The sample
      • Cookbook

Home page

The importance of the home page is self-evident and belongs to the first impression, and we need to capture the user, the appearance of the Vue home page:

The core:

  • Logo (Make others remember you)
  • Slogan – Progressive JavaScript framework (Attractive, want to find out)
  • guide
    • Why choose vue.js, in the form of video (overall introduction, 0-1 impression, with introductory theory, with practical project)
    • Get started – Get started quickly (once you are attracted, if you follow the steps to get started quickly, meet users’ expectations, or even exceed them)
    • Project Address: GitHub (Co-built, STAR)
  • Characteristics (tradeoffs, most attractive aspects)
    • Easy to use
    • flexible
    • efficient
  • Top station navigation

Overall, it’s all about making a good first impression and engaging users, and the point here is to reach out to new users and capture them.

The tutorial

Tutorials are obviously important for a project. The most important thing is to teach developers how to get started and make complex applications, and to help users understand the design and some of the details. In theory, you should be a qualified Vue developer.

We can see from the Vue tutorial:

  • basis
  • Learn more about components
  • Transition & Animation
  • Reusability & composition
  • tool
  • scale
  • inner
  • The migration
  • More and more

It covers everything from the basics to more ecological aspects. It’s comprehensive and easy to understand. This is the core of the course.

Let’s take a closer look at them in terms of basics, components, transitions, and animations.

Based on some

For beginners, the basic part is very important, here the most core is to treat the user as a pure new user, even to the front-end are not how to understand the user, step by step to teach them how to achieve the function, and these experiences are in the future in-depth use of Vue is also useful.

Do the same thing, and when it’s done, exclaim: Amazing! And, in addition, every part of the Vue tutorial has related video collocation, more vivid image!

Now let’s look at the core of the core, the basics of the tutorial.

Vue divides the base into the following sections:

  • The installation
    • A variety of installation methods to meet your everything
  • Introduction (Quick Start)
    • Tell you what Vue is
    • And then step by step N examples of what Vue can do
    • End with a component example
  • Vue instance
    • Where it all starts, the Vue application instance
    • Examples only, and detailed configuration items are linked to the API section
    • Vue components are also instances, which is inheritable
    • Data and Methods
    • Lifecycle hooks & diagrams (this diagram is so classic that almost any Vue related article sharing will encounter it)
    • Each section has an associated link to the API section to make it easier to understand this part of the whole
  • Template syntax
    • Explain the background, what you’re doing, and for the render function part, link to a separate module
    • Data binding: Interpolation
    • What is the command? What does it do
    • Abbreviations are really useful, basically all the Vue projects you see are using abbreviations, very concise and clear
  • Evaluate properties and listeners
    • The background, the scene to solve, and I’ll tell you how
    • Some contrast and difference, clear boundaries, so as not to abuse or create differences in understanding
  • Class is bound to Style
    • Vue’s enhancements to these two commonly used bindings are based on requirements or scenarios
    • A demonstration of how to write it
  • Conditions apply colours to a drawing
    • V-if related presentation
    • And v – show the difference
    • Best practice not to use with V-for, etc
  • The list of rendering
    • Array, object, value loop
    • Extending to array update detection, the core principle is linked to the deep responsive principle (this is also very important, all the responsive related basic included in it)
    • Some details case, link to component base /DOM template details (this will be missed by many people, there are a lot of details in Vue that actually relate to DOM templates)
  • The event processing
    • An important part of interaction is event handling
    • Usage of events and related modifiers (modifiers are one of many scenarios in addition to the basic ones)
    • Direct explanation of possible user queries
  • Form input binding
    • “Bidirectional binding” is an inevitable scenario, which is also one of the core scenarios in front end daily
    • What does v-Model look like when combined with various form items
    • Explicitly telling and bootstrating components can also use the V-Model
  • Component based
    • A basic example that shows you what a component is
    • Components are essentially for reuse, notes/pitfalls
    • Organization of components – Final tree
    • Prop component data transfer
    • The convention for a single root element
    • Component events (dispatch and listen)
    • Slot basic use, intuitive perception, no extra
    • Used in dynamic component scenarios
    • Points to note about parsing DOM templates
    • Various links to the deeper components will be covered above

It can be seen that the basic part of the content here is the most core thing: it takes you to understand different concepts and usages, without going into depth (there will be a special section to talk about, to link the past), focusing on the most core of this function may occur and related matters needing attention.

The whole model is roughly as follows:

  • Examples, get a feel for them, get to know them
  • Examples and explanations of various seed scenarios
  • What are the rules for possible potholes
  • There are some diagrams to help you understand
  • Each section has a video to help you visualize it

Basically, even if you are a beginner, you can understand the basic concepts and features based on what is shown to you. You don’t need to know much about them at this point, just know that there are these things, how they might be used, or what scenarios they might solve. You can find this part of the tutorial when you come across it in the future.

And a little detail:

  • The getting Started examples and basic modules are basically the same
  • Everything that needs to be understood in component basics is linked to the following “Understanding Components”, but the order is basically guaranteed

Learn more about components

This is basically an extension of the previous section on Basics/Component Basics. Components are one of the core designs in Vue, so it is necessary to have a separate, large section that describes them in detail.

Let’s take a look at how Vue gets to the bottom of this:

  • The component registration
    • Various cases of component names, as well as limitations
    • Global/local registries, their syntax, scenarios, and differences
    • Module systems and component registrations are combined, and even automatic global registrations of basic components are included
  • Prop
    • Case problem
    • type
    • The dynamic/static Prop case also includes ways to pass an entire object directly
    • The idea of one-way data flow, corresponding to the restrictions on Prop, cannot be modified
    • Prop validation issues, importance of component friendliness
    • Handling of non-prop properties extends toinheritAttrsConfiguration items and$attrsrelated
  • Custom events
    • Event name problem
    • The components covered earlier are v-model related and extended to$listenersrelated
    • Binding issues with native events.natvieModifiers and synchronization.syncModifier related background, introduction, use
  • slot
    • Definition, scenario: Content distribution, source Web Components specification
    • Scope, slot default content
    • Named slots, scenarios, and precautions
    • What are the problems solved by scoping slots
    • Dynamic slot name
    • An abbreviation for named slot
    • Other examples, slots related to some more powerful and flexible use
    • Related disuse instructions
  • Dynamic components & asynchronous components
    • Used on dynamic componentskeep-alive, starting from sample scenarios, and linking tokeep-alive(the core here is still the dynamic component)
    • Asynchronous components, nice functionality, details and configuration, basically all aspects of this scenario
  • Dealing with boundary cases
    • Access elements, components
    • Event listener correlation
    • Component loop reference
    • Alternatives to template definitions
    • Control update correlation

Although it is an in-depth part, the presentation basically follows what was covered in the basics: examples, focusing on relevant patterns. As an extra point, all of these sections are topped with a friendly reminder that you need to understand component basics to prevent problems caused by not knowing components (as can be seen from the title, it is an in-depth section with a certain cost).

Also, you’ll notice that there are a lot of explanations and rules for case, hump, and so on in Vue, almost all of which are derived from DOM template parsing.

Transition & Animation

Transition & animation is also one of the features of Vue, which is very powerful.

  • In/out & list transitions
    • Overview, outlining applicable scenarios and provided functionality, focusing on core entry, exit, and list transitions
    • Transition of single element and group valence
      • Various demo demo, CSS transition control, JS control
      • With the picture detailed analysis of the entire animation process
    • Initial render transition feature support
    • Transition of multiple elements, what scenarios and limitations
    • List transitions, scenes and usage, and FLIP animation support
    • Reusable transition, some scenarios, if we want to reuse, give you examples, and the best practice is to use functional components
    • Dynamic transition, we need the ability of dynamic transition in many scenes, for example, we do a unified package similar to the effect of the end of the native page switch, one is the forward animation and one is the reverse animation, is the use of dynamic transition
  • State transition
    • Mainly refers to the dynamic effect processing of data element scenes
    • State animation and listener, here the core is the use of Vue’s responsiveness to provide relevant capabilities can be very convenient to do some of the various dynamic effects, some examples of the demonstration
    • Bringing design to life, the final distillation, gives a more complex example of power

In transition and animation, you can see the great features available in Vue in detail, and make various examples and demonstrations of transition and animation to meet the needs of your various scenes.

Here are some of the tutorials we’ve selected and done some general analysis, and you’ll find that their patterns or principles are basically the same:

  • If necessary, give a general concept explanation. At the same time, when there is knowledge of dependent modules, give a striking reminder
  • There will be video support, or some scenes to help developers understand the graphics, produced a lot of classic graphics
  • Example by example, take you through the use of the current module, some considerations, version related information
  • There is some explanation of the focus, non-divergence, and current strong relevance, and others are described in more depth in a separate module if necessary
  • As a whole, it is more comprehensive and involves the introduction of each functional module of the framework as a whole
  • There will be some modules for in-depth understanding, but the purpose is to make Vue easier for users to understand, to really teach you how to use Vue
  • There will be some introductions related to the surrounding ecology, according to your scene to choose
  • Provides a good version migration guide with the appropriate tools to go with it

Additional, in the other modules, same in the scope of this tutorial, also contains some more in-depth content, but is designed to help you better understand the Vue, better use Vue, such as internal module of relevant content, deep reactive principle 】 【 is can help you understand the response of the Vue related principles, You can quickly locate problems when you encounter them. It also includes [comparison of other frameworks], which will be covered in more. You can see how the official compares some relevant frameworks and what ideas to analyze.

API

API is a set of all the interactive interfaces exposed by the framework. For this part, we need to do more than just list, but have some rules. Let’s look at how Vue does this.

  • Global configuration
  • Global API
  • Options/data
  • Options/DOM
  • Options/lifecycle hooks
  • Options/Resources
  • Options/Combinations
  • Options/Others
  • Instances of the property
  • Instance method/data
  • Instance method/event
  • Instance method/lifecycle
  • instruction
  • Special Attribute
  • Built-in components
  • VNode interface
  • Server side rendering

Some rules we can analyze:

  • Classification, subclassification to introduce, such as option whole and instance whole, option/data this kind of classification and subclassification, convenient for developers to memorize and aggregate; These two also cover the vast majority of the Vue API
  • Each API specifies the type, parameters, details, default values, return values, usage, references, and so on
  • If there are version-related changes for each API, they need to be identified
  • Each scenario in which the API cannot be used is clearly explained
  • Every API needs a straightforward explanation
  • Some commonly used apis can be linked to tutorials

In this way, you can not only understand the overall picture and classification of the overall API, but also understand what functions they can probably accomplish, so that you can easily and quickly come to the API for positioning if you can’t remember or need to confirm in the actual use.

Style guide

This is basically one of the most unique parts of Vue, and the official style guidelines that Vue developers should follow are specified. This is the best reference to help developers avoid mistakes, glitches, and anti-patterns. This is basically a Vue best practice, and you’ll find that if you follow this style guide during development, you’ll probably have no problems.

The style guide breaks down the rules into four broad categories:

And gave you a detailed explanation, to give you advice and reference.

Here are the detailed rules for each part:

  • Priority A: Necessary (error avoidance)
    • Component names are multiple words
    • The component data must be a function
    • Prop definitions should be detailed (type, default, required, and validation)
    • Set the key for v-for, that is, declare the key
    • Avoid using v-if with V-for
    • Set scope for component styles, but layout classes and apps and component libraries should not use Scoped, business scenarios are optional
    • Private Property name, namedThe $_The beginning even takes direct advantage of closure features to achieve private effects
  • Priority B: Highly recommended (for readability)
    • Component files, each component should be in a single file
    • The name of the single-file component, which needs to be uniform, is either PascalCase or kebab-case
    • Base component names, such as Base, App, V, apply to Base components of a particular style and convention
    • Singleton component names. Components that should have only a single active instance should be named with The prefix “The” to indicate uniqueness
    • Tightly coupled component names, parent-child component scenarios such as TodoList and TodoListItem
    • The order of the words in the component name should begin with a general description and end with a descriptive modifier, such as SearchButtonRun
    • Closures and components, but not in DOM template scenarios
    • Component names in templates are case-sensitive. PascalCase is recommended for single-file components and string templates, and kebab-case is recommended for DOM templates. Or use kebab-case everywhere
    • Component names in JS(X) are case sensitive and should always use PascalCase
    • Full word component name
    • The case of the Prop name, which should always be named camelCase when declaring the Prop, and kebab-case should always be used in templates and JSX
    • It is recommended that each attribute contains an element with multiple attributes
    • For simple expressions in templates, this is fine, but for more complex ones it is recommended to use computed properties or methods
    • Simple computed properties, complex computed properties should be split into multiple simple computed properties
    • Attribute value with quotation marks
    • Instruction abbreviations, all or nothing
  • Priority C: Recommendation (to minimize selection and cognitive costs)
    • Order of options:
      • Side effects: EL
      • Global awareness: name, parent
      • Component type: functional
      • Template modifiers: delimiters, Comments
      • Template dependencies: Components, directives, filters
      • Combination: extends, mixins
      • Interfaces: inheritAttrs, Model, props, propsData
      • Local status: Data, computed
      • Events: Watch, lifecycle hooks
      • Non-responsive: methods
      • Render: Template, render, renderError
    • Order of element attributes:
      • Definition: is
      • List rendering: V-for
      • Conditional rendering: V-if correlation, V-show, V-cloak
      • Render: V-pre, V-once
      • Global awareness: ID
      • Unique attributes: ref and key
      • Two-way binding: V-model
      • Other Attributes: All bound or unbound attributes
      • Events: v – on
      • Content: V-HTML, V-text
    • Blank lines in options
      • When you have more than one Prop, you can add blank lines to sort them
      • The order of the top-level elements of a single-file component
        • Single file componentShould always let<script>,<template> 和 <style>Keep the labels in the same order. and<style>Put it last, because you have to have at least one of the other two tags
  • Priority D: Use with caution (potentially dangerous
    • Not in thev-if/v-else-if/v-elseThe use ofkey
    • Element selector in scoped
    • Implicit parent-child component communication, that is, not through$parentOr change prop (if prop is an object)
    • Global state management, instead of using state management like Vuex, using time bus or$root

This is a specification, a best practice, and if everyone follows this convention, it will be much cheaper for everyone to read code or CR. Also, it can reduce the occurrence of many errors or warnings.

The sample

Example Example is a complete demonstration, rather than a series of small demos shown in this tutorial. In essence, this example is a mini application.

Vue contains: Markdown editor, GitHub Submission, Grid Components, tree views, SVG ICONS, schema components, Scalable Headers, embedded components, Real-time deepstreamHub, Firebase + Validation, ToDoMVC, HackerNews clone.

Each of these examples basically uses a different Vue feature, or is written and organized in a different way, most of which you can see directly on the official website. It’s very intuitive, and you can modify it further to make your own examples.

Cookbook

First, recognize the difference between Cookbook and tutorial, which is also described in detail in the documentation:

So what is the goal of the Cookbook?

Vue currently provides this section of content according to the following rules:

These are explained in detail in Vue, including motivations, goals, and specifications.

Why

In my opinion, one of the core points, as an open source project, even as a project, is that if you have users, how they can use your project is very important. Word of mouth is definitely not an option, so it’s all about documentation. Documentation also has the added benefit of SEO, which further enhances the ecology.

Documentation first, or getting documentation right, is a critical point in the open source world and, to exaggerate, can in some cases be the difference between life and death or the life cycle of a project.

It is generally accepted that Vue documentation is well written, so from the point of view of reason, this is the core of the Vue open source project and an integral part of it. Not just good code, good documentation, good testing, good open source collaboration, etc. This is the core attitude of being responsible for the project and the developer. Of course, the effort will be rewarded. I believe that it is because of the comprehensive and easy-to-use Vue documentation that the Vue ecosystem has become more prosperous.

conclusion

We basically analyzed the contents of some core modules of the Vue document, including:

  • Home page
  • The tutorial
  • API
  • Style guide
  • The sample
  • Cookbook

Through a detailed analysis of them, we can find that Vue in the whole document design, or do a good abstraction and classification. It doesn’t feel like a lot of documentation to developers, but at the same time it feels hierarchical, with clear responsibilities for each module part.

Here we can make a general summary and thinking, so that we can use for reference and learn when writing documents in the future:

The overall outline

  • Home page
  • learning
  • ecological
  • team
  • resources
  • Sponsorship, support
  • Multilingual and translated

The core of the core here is the home page, learning and ecology. And for the learning part, a level of disassembly is carried out:

  • The document
    • The tutorial
    • API
    • Style guide
    • The sample
    • Cookbook
  • Video tutorial
    • Place for various video tutorials

For us, it is also possible to learn the outline form of this document by reference, and add and delete according to our situation as needed.

The content and dismantling

In this part, the main core is the disassembly of five parts in the document:

  • The tutorial

    • Start with the basics, focus on the current demo demo, notes
    • Assuming developers are zero-based, anything that needs to be explained or guided needs to be given
    • The complex part, single out the module to explain in detail
    • Regardless of which part, note that the correspondence is consistent with the perception of the developer
    • Difficult to understand, can be illustrated with the help of pictures

  • API

    • Completes the classification
    • Detailed tabulation by individual category
    • The core of the API must ensure that the input and output are defined, described, and versioning information

  • Style guide

    • The official recommended code style, hierarchical presentation, and recommendations Vue developers should follow

  • The sample

    • The point of a complete project presentation, planning out the Vue functionality they use, is certainly not simply a stack of examples
    • It’s best to see what you get, or try editing to see the effect

  • Cookbook

    • Follow the principles of being more focused, deeper, teaching JavsScript, exploring the ecosystem
    • The goals are:
      • Solve a specific universal problem
      • Start with the simplest example possible
      • One complex point at a time
      • Link to other documents rather than reexplain concepts here
      • Describe the problem clearly, rather than assuming familiarity with it
      • Explain the process, not just the end result
      • Explain the pros and cons of the policy, including what scenarios does it not apply to
      • Relevant alternatives will be mentioned, but will be covered in detail in a separate case
    • Paradigm:
      • Basic example
      • The detailed value of some details
      • Practical examples
      • Extra context
      • When to avoid this pattern
      • alternative
    • This is a way to know what’s going on, much deeper than a tutorial

It can be seen that for different modules, the core of our disassembly is still different, but it cannot be scattered. They are related to each other. When there is related to each other, it is to link to jump to each other. The final form is an overall division, each module is combined with each other, there is a certain level of such a dismantling way to explain, for developers to learn, refer to.

other

Of course, this is not to say that other parts are not important, this is selected according to the project situation, we here are more examples, through the outline and disassembly, can help us write a better document:

  1. Awareness: Documentation is important, indispensable, even more important than the project itself
  2. Prerequisite: Developers are new to the game and dependencies should be clearly described
  3. Content: integrity, hierarchy, module clearly divided, module content itself focused, not divergent
  4. Language: simple, accurate and easy to understand
  5. Ecology: Give description and entry to solve more of your problems
  6. Team: member honor, but also the embodiment of influence