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.
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!!
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.
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.
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.
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.
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.
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.
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?
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 :)
