Better documentation

[kmalakoff]

There is a proposal from here to write a better walk-through based documentation: http://groups.google.com/group/knockoutjs/browse_frm/thread/480112c00aa37cae#

"While I've played around with BB and am using KO in production, I'm a bit unclear how they fit together. I've always been a big fan of the spine.js documentation. In the following example, I like how the author walks through the app from html to model to controller to view. I'd love to see something similar with Knockback, even if you just skipped the narrative bits inbetween the code. http://spinejs.com/docs/example_tasks"

Everyone fine with spline-like documentation or do you prefer jsfiddle-like documentation from Knockout? (I'm saying this without knowing what I'm actually getting myself into on the documentation since this would be my first documentation site so any help like making me a template site would be much appreciated!).

[kmalakoff]

We've released a todo app with enhanced features to document the API: https://github.com/kmalakoff/knockback-todos

We need to put it on a live site: https://raw.github.com/kmalakoff/knockback-todos/master/todos.html

[kmalakoff]

The todo app is live here: http://kmalakoff.github.com/knockback-todos

And the new website thanks to @yuchi is here: http://kmalakoff.github.com/knockback

[dzhus]

Narrative tutorials and example apps are fine, but definite API reference is above everything, currently the most useful part of Knockback docs is what starts with words «The library includes the following classes:» in the Readme. I would personally prefer adding bare JavaScript in the reference. knockback-todos is a bit dumbfounding.

[dzhus]

Consider this:

A kb.Observable is used to observe a model attribute and update itself or notify its subscribers when it changes. It has four main patterns:

What should really be present in the docs is simply what arguments kb.observable() accepts and their semantics. Currently I had to recollect it from random code snippets scattered all across READMEs for knockback and knockback-todos.

[yuchi]

I'm looking at codex to see if it's a good solution to build the docs for KB. Looks very promising.

[kmalakoff]

@yuchi: Hi Pier! In preparing for 0.15.0, I took a look at codex. Unfortunately, it wasn't very good. The main problem is that it really doesn't handle directory paths well.

I decided to roll my own build scripts instead (and did a major refactor of your original work). Take a look here: https://github.com/kmalakoff/knockback-site.

It is not ready for release (still need to fill in the content), but I'd appreciate any feedback you have.

Cheers,

Kevin

[kmalakoff]

There is now an API reference in the Knockback website. It is still a little rough, but it should go some of the way: http://kmalakoff.github.com/knockback/

[yuchi]

The layout now is seriously broken, but I'll fix it ASAP rewriting the design for bootstrap, so you'll be able to continue the development of the site directly with bootstrap's goodness :)

Just give me a dead-line, I'll try to stick to it!

[kmalakoff]

@yuchi : zen be with you...

[kmalakoff]

@yuchi get the latest and make it awesome!!!

[kmalakoff]

Yeah, I had to hack around the stylesheet to make it not look too bad, but I thought you might not be satisfied ;-P

Can you let me continue with the factoring and updating of the web site over the coming week or so (i might restructure things some more making merging more difficult) and then I'll let you know when you can fix it properly?

On May 11, 2012, at 6:06 PM, Pier Paolo Ramonreply@reply.github.com wrote:

The layout now is seriously broken, but I'll fix it ASAP rewriting the design for bootstrap, so you'll be able to continue the development of the site directly with bootstrap's goodness :)

Just give me a dead-line, I'll try to stick to it!

---

Reply to this email directly or view it on GitHub: https://github.com/kmalakoff/knockback/issues/7#issuecomment-5646675

[yuchi]

I've done some improv on the docs section, you can have a look at http://yuchi.github.com/knockback/docs.html (I didn't want to build the GH pages for it, but it happened once I pushed the repo :\ )

[kmalakoff]

Hi Pier,

Sorry for taking so long to get back to you. I've been working on a project deadline.

The documentation looks good. Is it mainly the font size that has changed? (I think I needed to override the list-related element styling before)

As for building GH pages, just send me a pul request and I'm not sure if, now that I've seen your changes, you should try to redirect from your repository's website to the official one. Just choose what you believe it best given it is actually good to see the version live for review.

[kmalakoff]

Hi Pier,

Sorry I have taken so long to follow this up. I've been doing some freelance work that took up too much time!

I've like to merge in your style changes but can't seem to find the .styl files (and can't figure out how to access your gh-pages branch...there is a cool green icon at the bottom of your page https://github.com/yuchi/knockback-site, but no branch).

Could you submit a pull request?

Cheers,

Kevin

[kmalakoff]

Hi Pier,

I haven't heard from you for a bit. I'm hoping you are not mad at me, but just moved on....I'd still le to get you styl improvements for Knockback.

Today, I released 3 objective C libraries (I'm currently doing freelance iOS development is Japan). _.m and QUnit.m, and SubjectiveScript.m. Do you do iOS development?

I hope you are good and that you are enjoying the summer.

Kevin