A Comprehensive Documentation and Tutorial

[ganarajpr]

It would be great if rivets had better documentation. There are quite a few features that are totally missing from the documentation section altogether. The documentation should not only explain these concepts but also provide examples of how to use them.

For example, things like rv-if rv-unless etc are totally missing from the documentation. There is no documentation which explains how to create your own components. An example that shows the various things you can do ( various options available ) when creating a component would be great.

Rivets creates new contexts ( how do you get hold of these contexts in javascript if they are created by rivets ? ) - documentation explaining the various built in binders which create new contexts would be great as well.

[gtsiokos]

I'm pretty sure @mikeric knows what he is doing but i have to agree. Recently i started using rivets for my company's frontend mobile toolkit.

I loved the minimalistic opinionated design philosophy compared to the huge reactive libraries out there but documentation is harsh and i'm confident the results would be far more elegant if Rivets had a comprehensive "Beginner to Advanced" guide.

I'm looking forward to have a better understanding of binders, adapters and advanced use-cases (partials, observer augmentation). In general, stuff that probably are there but we don't know.

[ocke]

I completely agree. I had no idea how to get this thing on the road! Also the 'examples' on the main site are just hilarious non-informational. They show just part of what is needed to get going.

That said, I would love to help out and create better docs!

[jkupferman]

I was in the same boat of having difficulty to get started, so I put together a quick "getting started" fiddle for rivets + watch.js: http://jsfiddle.net/jkupferman/WgsF8/2/

It's just the minimal set of code required to do basic data binding. All of the existing code I found around the internet was busted because of the rv- attribute name change.

[jonwyatt-mas]

@jkupferman - brilliant - having struggled with the 2-way binding example at http://www.rivetsjs.com/docs/#binders, your fiddle just worked. @mikeric - please add a link to the fiddle to the docs as the current code example throws errors?

[boycce]

Can't agree more. Looks like an awesome project, but unfortunately it lacks in the docs. First thing I tried to find meaning of, was the extensive rv-* declarations. I guess the only way to grab the list of usable binders is through the source.

[mikeric]

This article seemed to get recommended often (even though it's from 2009, it all seems relevant and pretty sound for writing good docs, specifically the What to write segment). I've learned quite a bit from this.

http://jacobian.org/writing/great-documentation/

It's also obvious to me now that this page is probably what people are hoping to see under documentation on the website, rather than the mixture of explanatory text on there currently. @incompl pointed this out in #298 and he's right. If that page was a bit more detailed and included all binders as of 0.6.8, it would make a good "Binder Reference" section.

Could we perhaps define the different topical guides that people would like to see appear on the homepage? (excluding components, because that API is changing and not well defined at the moment).

Should the documentation be structured differently than this? Anything missing?

• Documentation

  • Guides

  • Getting Started

    • Quick Start

    Only covers including the lib and binding to a basic template using rivets.bind (without bringing formatters or adapters into the mix). Basically just enough to show someone how to get something working without over-complicating things from the get-go.

    • Writing Templates

    Covers how to compose templates using the two declaration methods that Rivets.js provides (rv-[binder] on elements, and { ... } for text interpolation). Should also explain that all binding declarations in your template follow the same universal syntax [target] | [formatter] [args].

    • Binding and View Lifecycle

    Covers rivets.bind, view.update, view.sync, view.publish and view.unbind.

    • Configuration Options

    Covers rivets.configure and the available configuration options.

  • Binders

    Covers how bindings actually work and how to create your own.

  • Formatters

    Covers how formatters actually work and how to create your own.

  • Adapters

    Covers how adapters actually work and how to create your own.

  • Components

    In progress.

  • Binder Reference

  An index of all built-in binders available to use in your templates, along with a usage example for each of them.

  • Tutorial

  In progress.

[mikeric]

Another thing to do is to store the documentation in the repository itself under /docs or just to start using gh-pages again. This would enabled people to contribute easily and would version the documentation alongside the code.

Let me know if these are all favourable changes.

[mikeric]

@toxinhead Added a binder reference here. http://rivetsjs.com/docs/reference/

[boycce]

@mikeric Thanks, yeah I noticed that, I can delete my notes now. Docs under /docs sounds good to me, although the sites styling is very seductive.

[ganarajpr]

@mikeric This is a great start. I would add that example plunkers or fiddles showing the actual binder working and embedding them in those locations , along with the documentation, might make things even easier to understand. I am sure the community can take up this additional task.

Separating out the docs to its own section is an amazing idea.

[jhnns]

:+1: for pushing the docs