Documentation improvements

[oliverjanik]

I like your project. A lot. But in order to drive adoption the docs need to improve significantly.

I read all of the docs and I was left confused. There is a lot of assumed knowledge e.g. experience with react or polymer. Why is the project called hyperHTML but the documentation talks about viperHTML? I for one do not care about server side rendering (I had to google what SSR even is). Very confusing to newcomers.

Under the hood is way to early in the docs. I was left very confused. First time I saw tagged template literals. I think you need to sell the simplicity, performance and composability first. Random visitors to your page will be put off by that Under the hood page right off the bat.

I think you're missing a very basic getting started page with clear examples. Right now there is a lot of inconsistency. Like the docs talk about bind and wire but then it says just use hyper() overloads it does not explain where hyper comes from and all the examples still use wire and bind.

Docs also need a guide section where common patterns are covered. How do i render an array? How do I do if else in the template? how do I re-render by component based on an input change? How do I compose components? Can I re-render a single sub-tree? How do I incorporate promises into my components i.e. data coming from fetch. I know people can figure these things out but an official "best practice" would not hurt.

A complete and clear API surface reference would be great too. There's a lot of random mentions of random functions that hyperHTML exposes, but not a complete reference. Some examples have html tab before the literal. What is that? Where does it come from? How about render tag before the literal ?

I love the idea behind hyperHTML and I wish it success. I'll start using it for my side projects. Some of the things I mentioned might be obvious to you but will not be obvious to newbies. And some of the things I mentioned are already documented, they're just buried in random links to codepen or misplaced. I believe half the success of Vue.js was it documentation.

Let us know you accept pull requests and how we (developer community) can help you.

[joshgillies]

@oliverjanik thanks for the feedback. Pull requests are absolutely accepted see https://github.com/viperHTML/viperhtml.github.io/pulls?q=is%3Apr+is%3Aclosed, and of course feel free to put forth any of the above improvements against https://github.com/viperHTML/viperhtml.github.io. We (developer community) can and should work together to make hyperHTML and it's supporting documentation great!

[WebReflection]

Why is the project called hyperHTML but the documentation talks about viperHTML?

where exactly did you read that? I have found 4 mentions to viperHTML in the documentation and these are for a single adopt experimental method and to describe the name.

can you please point at the documentation that talks about viperHTML ?

how do I do this and that ... ?

there are tons of examples in the example page, all with live Code Pen. Those examples are basically the entirety of every other framework Getting Started examples, reproduced with hyperHTML. If others covered, then it should be covered for hyperHTML too.

There's a lot of random mentions of random functions that hyperHTML exposes, but not a complete reference.

The API section explain those two methods. hyperHTML is a two methods API with a simplified entry point for both of them.

That's the summary of the API: is it really that hard to understand?

Some examples have html tab before the literal. What is that? Where does it come from? How about render tag before the literal ?

I am not sure what you are talking about in here. HTML tabs? String literals are just strings, you can put in there whatever you want.

Some of the things I mentioned might be obvious to you but will not be obvious to newbies.

There are two kind of newbies: those that no matter how good is the documentation will never read it but will ask gazillion live examples, and those that prefer documentation.

I'm trying to make both kind of users happy and few are already helping a lot with the documentation.

Let us know you accept pull requests and how we (developer community) can help you.

like @joshgillies said, the whole site is Open Source (and statically hosted on GitHub) and of course pull requests for the documentation are more than welcome.

The repository is here: https://github.com/viperHTML/viperhtml.github.io

Thanks for the feedback.