Hacker News Reader

Comment by couchand | Hacker News Reader

There's quite a bit about this library that I'm excited about, the small module philosophy, for one. But I started digging in and am finding typos and errors all over the place in the docs. Either this is still a work-in-progress (which would be surprising since it's major version 4) or the maintainers just aren't spending much time keeping up the documentation.

To the core team here and anyone making a library: please make sure your documentation is flawless and your example code exemplary. Thanks!

View on HN

With regards to "major version 4" we are doing our best to follow semver, where backwards incompatible changes require a bump in the major version.

So yes and no, this is a work in progress (what isn't) and we will constantly be pushing to make the docs better. We've been working hard over the last couple of weeks to get this into some form of a publicly releasable state, but yes it's not perfect :)

If you want to help us out, feel free to submit PRs or issues on github. The main site is at http://github.com/ampersandjs/ampersandjs.com while the API references are generated from their individual readmes, all available in that github org.

I do often submit PRs for occasional typos in docs, but I don't really feel like copy-editing a whole README, which is what's required here. I'm not trying to be difficult, just honest.

I appreciate the use of semver, but I don't think the intent is to go through three major versions in as many days...

Sure, I wasn't expecting you to copy edit if you don't want to, just pointing you to the source.

> I appreciate the use of semver, but...

Oh, we aren't breaking things _that_ quickly! ampersand-state for example has been a repo since February.

Thanks, it was actually the READMEs on GitHub that I was referring to originally. I'd bet those don't get the same level of care the website does.

I'm really not trying to be annoying, but I'd point out there was a week there in April where ampersand-state jumped from 0.5.0 to 3.0.1. Perhaps it's just that the initial decision to one-dot was premature and now you're locked in by semver?

Well generally with semantic versioning, you only get to major version 1 once you have a piece of software that is feature-complete and production-ready. Changes in the API don't require a major version bump if you're not at 1.0 yet.

Reply on news.ycombinator.com