Hacker News Reader

Comment by micheljansen | Hacker News Reader

I just want to compliment the OP on a very clear and comprehensive website at https://imba.io/. It clearly explains (by showing and telling) what Imba is, why I should care, how it works and how to get started. The floating demo applications even work well on mobile. Rare to see this level of polish for these things.

View on HN

I've noticed that some projects being complimented for having good docs come from CTOs (esbuild is another example). I'm hoping that by pointing out this little correlation, people might feel more inclined to spend more time on writing docs for their projects if they aspire to climb in the career ladder :)

Thats a very good point. In my company whoever writes the most valuable and extensive docs are looked up by people automatically. Either for clarifications or just networking. For the past couple of months I have been making devtools for QA and documenting them and just recently found out that every single team uses them and got recognized for it in the all hands!!

Any extra salary? No of course not. Lol.

Anecdata, but after I released Mithril.js, I started getting contacted by recruiters from Bay Area companies. I now make 4 times as much as I did when I first started working on it. I know of other folks that got poached by high tech companies due to growing prominence in open source.

FWIW, my experience reflects GP that people really appreciate someone who takes the time to teach/help others. YMMV.

Was your original salary at the average market rate?

And it's very well deserved, Mithril is amazing!

I never had a really successful OSS project but I have a few friends who had or were maintainers of successful projects.

One got poached by FB, another one is a contractor at a higher than average rate.

Working on OSS and working for high tech companies are two things that are diametrically opposite. The latter is not a reward for the former, unless you were only ever writing OSS to pad your resume.

In my experience, it's not an either-or thing. I started my project to scratch an itch and only released it because I thought it could be useful to others. It originally didn't occur to me at all that my side project might influence my own career. But turns out that having a lot of stars on github attracts the attention of recruiters who use bot-based tooling to find talent and hitting HN front page attracts lurker employers. Getting stars is correlated with usefulness, and good docs correlate w/ usefulness as well. There doesn't need to be a direct causation relationship or even any specific intent, all that matters is what actually ends up happening when multiple correlations interplay.

Also, you can write open source software in big tech companies and even be paid to do it (React core team is a good example). TC39 folks spending time moving the Ecmascript standard forward is another example of staff/principal engineers doing citizenship-oriented work in order to get recognition for impact at FANG L6+. Being snarky about it doesn't change the fact that these sorts of symbiosis exist.

Ha ha no. I didnt even have a discussion about that. I think i need to talk to my manager at some point. But he has been very supportive!

Just out of curiosity, what is your age? You can give a range if you are not comfortable sharing the exact number.

bro i'm 150,000 to 300,000

PostgreSQL, FreeBSD, Debian, rails all have superb docs.

Also, the software quality is high. This used to be the case for Apple and windows sdks. Not anymore.. now it’s “read the code“ or stack overflow

Very true!

One small note to the author: the “We are hiring” at the very top, on mobile, is a bit broken. It appears on three lines. It looks great in mobile landscape, but not in mobile portrait mode.

One piece of feedback: it took me a moment to work out what 'pt', 'o' and 'fs' were. Single character variables are fine for algorithms but for demos you really want to use actual words.

I’d agree If I’m using css daily I might know what these mean, but I only edit css once in a while, so most of these properties are lost on me

I write CSS everyday and I had no idea what "fs" meant.

"fz" is the typical shorthand used for font-size (at least by Emmet-style autocompleters). "fs" is used for font-style instead.

Those shorthands are optional.

Great but they shouldn’t be used in demos.

Oh YES ! 100% - or if the demo spans "multiple files" but the code-snippets doesn't include a filename comment.

I.e //app.js ...

//my-todo.js ....

One thing that site does not specify is the Imba's license (MIT)

What does it mean for projects build using imba?

Nothing you should worry about. MIT is a very permissive license.

On side note, if you ever wonder what a licence means or do there is this website that help clarify this : https://tldrlegal.com/

You have to worry about including the copyright and license in your software. I've never seen a project do that so I'm not sure how to do it or if MIT is actually usable.

The attribution clause only applies to the licensed code, not derivatives. In practice, all this means is that you can use an unmodified copy of Imba (which contains its own license/attribution language) without issues.

What's not cool is to fork Imba, remove the attribution to the original author and pass it off as your own code.

Exact opposite of Elastic.co.

Every time I consult their docs, I feel like I have less of a handle on the topic than when I started.

Hate to pile on, but I'm glad it's not just me. When I read their docs, I just get the feeling that I'm kind of dumb, or I just don't have the context they expect me to have.

This. It almost like their docs is a cheat sheet for the Elastic devs, not for the end users.

I think this might be partly due to the query language being JSON? It makes every example huge and hard to understand. JSON is a serialization format that's human-readable, it's not a human-first language. So it's a pity that's how you're expected to write searches (I know they have some SQL support now, but I've never seen it in the docs)

I don't think this has anything to do with json or examples in general. At least not for me.

Quite often after reading their doc I just don't understand what result I should expect. Also the whole documentation simply lacks sane navigation. It's almost impossible to find anything there without google.

In 50% of cases this is how it works for me (exaggerated):

Question: how do I sum two integers?

Expected Answer: You should use SUM(). The result of the function is the sum of two integers. Examples:

2 + 2 = 4

2 + (-2) = 0

-1 + (-1) = -2

Answer from Elastic docs: Well, you should execute this query agains this API, which will launch X subroutines in Elastic engine and the final result will be the result of of the aggregation of function defined by the Ex with En+1 being your query's body field Y with respect to url query param N.

Is it just me? This website is super laggy on my PC (which can run modern games just fine). Hardly hits 50 fps when scrolling. How slow can one get and still claim to be fast?

Not just you, I have a pretty beefy desktop and it's noticeably laggy when scrolling for me too.

EDIT: ah - butter smooth in edge (and presumably chrome too), but laggy in firefox.

Further update - it turns out I'd turned off Hardware Acceleration in FF to avoid issues that Windows has when you have GPU accelerated content on two separate monitors with different refresh rates.

It's really bad with Hardware Accel turned off, but it's still a bit laggier with it on compared to chrome/edge.

Yeah, it's not really optimized for that. The floating labels over the code examples are offset in 3d space (for a subtle parallax effect while scrolling), so when HW acceleration is off it may end up repainting the page on every scroll. The effect is probably not worth the tradeoffs :)

Firefox 91 on Windows. 2011 CPU. Radeon RX 570 GPU.

I have a low spec PC, and it is running just fine.

Maybe some extension slows down your Firefox? I don't use an anti-ads and anti-spam extension, I deal with that via hosts file.

Very true! It's a great landing page for a language that gets into the meat of it right away with clear examples in code blocks. Nice work.

I love the font chosen for the demo code, the descender on the f is very charming.

I thought so too

Reply on news.ycombinator.com