← Back to context

Comment by micheljansen

4 years ago

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.

40 comments

micheljansen

Reply
lhorie  4 years ago

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 :)

  • jbverschoor  4 years ago

    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

  • vijaybritto  4 years ago

    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!!

gregsadetsky  4 years ago

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.

nailer  4 years ago

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.

  • rawoke083600  4 years ago

    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 ....

  • linux2647  4 years ago

    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

    • greggturkington  4 years ago

      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.

system2  4 years ago

Exact opposite of Elastic.co.

  • meepmorp  4 years ago

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

    • vosper  4 years ago

      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)

      1 reply →

    • ziftface  4 years ago

      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.

      1 reply →

js6i  4 years ago

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?

  • Shorel  4 years ago

    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.

  • p1necone  4 years ago

    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.

    • p1necone  4 years ago

      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.

      1 reply →

dtagames  4 years ago

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.