Documentation Needs to be Modernized and Improved

[methodbox]

Your documentation is, and has been for a very long time, extremely shitty.

Your basic examples cannot be used as-is without significantly more code that isn't explained on your site or in your github.

Your example:

<div class="entry">
  <h1>{{title}}</h1>
  <div class="body">
    {{body}}
  </div>
</div>

var context = {title: "My New Post", body: "This is my first post!"};
var html    = template(context);

Doesn't actually work without a LOT more involved. It's terrible documentation and results in the rest of us having to go to many third-party sources to learn how to use your code.

Precompiling, touted as the way to go in terms of performance has even shittier docs:

<script id="entry-template" type="text/x-handlebars-template">
  <div class="entry">
    <h1>{{title}}</h1>
    <div class="body">
      {{body}}
    </div>
  </div>
</script>

var source   = $("#entry-template").html();
var template = Handlebars.compile(source);

...and you want to "learn more"??? about precompilation you offer this:

Handlebars.templates.person(context, options);

Which we both know is bullshit and doesn't explain how to actually render the template.

Of course, you could use the cop-out that "everyone knows Mustache" and reference their docs, but that is arguably the worst documentation of any JS library yet.

This documentation is so bad I had to review how to actually get a partial to render from 3 other sites to actually get it to function. Most of the HBS tutorials are out of date and do a relatively poor job explaining much more than your own.

I'd really like to use Handlebars as I've used "Spacebars" in Meteor, but Meteor is it's own nightmare, though the templating is pretty smooth.

Handlebars obviously has potential, but to have precompilation and basic partials & templates explained in such a lazy way it makes it very unattractive to continue to force my way through it.

[ajfarkas]

I'm just starting to work with Handlebars, but I'd be happy to team up with someone to improve the documentation.

[jacobrossdev]

I actually landed here from the link at the bottom of the page. I agree the documentation assumes you already have a grasp of handlebars. I would suggest more context in the examples provided. If anyone arrives at this thread, frustrated by the lack of context in the documentation, this tutorial from Treehouse was very helpful http://blog.teamtreehouse.com/handlebars-js-part-2-partials-and-helpers. There is a download link at the button of the post with working examples.

[calebjay-ei]

handlebars.registerHelper is tragicomically bare. Doesn't even give the arguments to the function. What happened?

[milenvoutchev]

https://devdocs.io/handlebars I've found to be of great help. Hope this helps!

Original post https://github.com/wycats/handlebars-site/issues/192#issuecomment-482060778

[nknapp]

I have created a new draft site at https://handlebars-lang.github.io/docs/. You can help by making pull requests copying content from the old site. Or by creating and improving new content.

Please do not copy raw content from any blogs or other documentation sites without their permission.

[methodbox]

I have longgggg since moved on from HB but I'll take a look when I get some time. Maybe I can at least contribute to the docs.

Can I start by suggesting we review the code for opportunities where JSDocs comments would help explain functionality in a way that also makes it more useful in the IDE? Like maybe using TypeDoc for starters?

Something like

/**
* ```js
* @blockexpression
* A block expression uses double-curly braces to indicate 
* interpolated code blocks within your HTML
* ```
*/

{{ blockexpression }}

EDIT - To be clear, I’m suggesting both reviewing the existing code for JSDocs-compatible comments (I didn’t find any on a quick look) and placing PRs to add them as needed, which we could in turn use to pull them using TypeDoc to make the new docs site more useful and accurate.

But that would require buy-in from @wycats, who doesn’t seem to have shown any interest in updating the previous “docs”. —end edit

There is also nothing regarding TypeScript; not sure if @wycats has any intention of addressing that or if this lib is just too old for it to be relevant anymore to those who actually use it?

[nknapp]

new site is up.

[methodbox]

@nknapp While again, I haven’t used HB for a long time, I reviewed the area of the site that sparked this issue and it’s definitely a lot clearer how to get started.

That said, like almost every other docs site out there, you might consider a “Getting Started” link. Your “Usage” section (the one I was clearly infuriated by when I posted this in 2016) is close to including what I’d expect in a Getting Started.

Just my 2 cents.

Thanks for doing this as it’s important for those who might need to pick up HB.

[nknapp]

Thank you for making the effort to write this answer despite not being involved anymore.

I would like to make sure we both talk about the same thing. Do you mean that the "Usage" section from the "Installation" page should be at a more prominent position and directly linked from the home-page?

[methodbox]

@nknapp Yes, that and maybe add a bit more to it in terms of tutorial content.

That section is what I’d expect to see as “Getting Started”, but I’d also expect to see a bit more explanation to get started.

Like a literal, step-by-step working example. That’s generally what you see with other libraries & frameworks (exa. React, Bootstrap).

[nknapp]

The thought behind the current structure is, that a CDN is about the easiest way to start with, but under no circumstances should you use it in a real project. It is just so much easier then installing node, which is the actual use case in my eyes.

I actually don't want to promote using Handlebars in the browser at all anymore, there are way better frameworks for that today (Vue, React, Ember, Angular, to name some).

But I still have to mention it, because it is possible, so I moved that part as far to the back as possible.

And, one thing that is special about Handlebars is that there many implementatios in different languages (Java, Rust) which is what I tried to keep the focus away from JavaScript as much as possible

Those were probably too many thoughts at a time. I'll think about it. Thanks for your feedback.