[rgbrgb]

I know it seems superficial but beautiful docs are one of my most trusted heuristics when I'm considering using a library. If the author cares about the aesthetics of the docs, it often means they care about the aesthetics of the code, which really does matter a lot. We can make ugly things or we can make beautiful things. I really respect people who take the time to make beautiful tools.

[VikingCoder]

Was that intended to be a compliment of this project? I had the opposite reaction. I accept that English is often a second language, but this page was off-putting.

Sophia is a modern [should add comma] embeddable key-value database designed for a high [should hyphenate] load environment.

It has a unique architecture that was born as a result of research and rethinking primary alghorithmical [sic, should say "algorithm"] constraints associated with a [sic] getting popular Log-file based data structures, such as LSM-tree [should say "trees"], it's [sic] variations based on Fractional Cascading ideas and a B-Tree. (see architecture) [run-on, meaning unclear]

It is very fast. (see benchmarks)

it [sic] is easy to use. (see documentation)

Implemented as a small C [should probably hyphenate, or just rewrite] written, BSD [should probably hyphenate] licensed library.

[jasonwatkinspdx]

It's quite clear English is not the primary language of the author, and I think it's in poor taste to criticize grammatical errors that are clearly sourced in this.

English is not an easy second language to learn as an adult, and technical English doubly so.

[falsedan]

These are basic grammar mistakes. Mastery of basic grammar is achievable with a small amount of dedication; if the author does not have the time, they could ask an English-speaking acquaintance to proof-read their docs.

The author's primary (and perhaps only) contact with users is through their documentation. Incorrect capitalization and apostrophe use is distracting and will put off some potential users. The author looks sloppy and uncaring because these types of mistakes are preventable.

Being a non-native speaker is not an excuse for basic errors (excepting novices). Proof-read your docs! If you're not confident in your language skills, ask someone else to!

[runarb]

if the author does not have the time, they could ask an English-speaking acquaintance to proof-read their docs.

I doubt it is the lack of time. But natively English-speaking acquaintance to proof-read technical documentation can be very hard to come by. Most projects have to do by with the folks they have. ( I am in need for such a person myself. If anyone has the time Searchdaimon ( https://github.com/searchdaimon/enterprise-search ) could need some help :) )

One trick can be to at least wikify the documentation so other can easier pitch in.

[jasonwatkinspdx]

To be blunt: do you speak a second language fluently? If not, I don't think you have any idea how much dedication you're demanding.

Instead of bashing someone on hnews comments, you could send them an errata patch.

[falsedan]

The onus is not on me to make this project's documentation presentable: it is on the author. My language skills are immaterial! The author's language skills do not excuse lazy presentation, they only help explain it.

[jasonwatkinspdx]

They are material when you say that the author is being lazy for not writing English better or finding someone to contribute. It implies you don't know the difficulty of what you're asking, so why are you calling him lazy?

But of course you want to make it clear that you feel no obligation to contribute despite your criticism. So it's lazy for him, but not for you?

[VikingCoder]

I wish that I had spent more time crafting my initial response. How would you have written my post, so these concepts are clear:

rgbrgb, I agree that it's superficial, but in direct contrast to your praise of the superficial style of the documentation, I was unfortunately distracted by the superficial mistakes in grammar and spelling. I wish someone would take the time to help the author of this code, Dmitry Simonenko, to improve the documentation. To that point, here are my hopefully constructive criticisms specifically of the language used in the documentation. I have performed no audit of the library itself, and cannot speak to its quality.

Does this still come off to you as poor form?

[jasonwatkinspdx]

That's much more reasonable. But I also think it's a waste of time.

The problem with the docs aren't these small gramattical errors. In most cases you cite the meaning is clear, so this is just pedantry.

What bothers me about the documentation is that the explanation of his algorithms is a bit opaque.

But all told, I'd much rather someone contribute than hold back because of concerns about language mastery.

[VikingCoder]

I, like many people, get distracted by easily-corrected mistakes. You can call that a fault of mine, and people like me, but since it's relatively easy to lower the barrier for us to easily consume the material by correcting the language, I think it's worthwhile.

[dilap]

I don't think you're weighing the "English-as-a-second" language factor nearly strongly enough. While grammar can be a great proxy measure of quality for works by native speakers, it's completely inappropriate for non-native speakers -- the amount of effort required to reach native-level fluency and polish (i.e., at the level of your critique, above) is herculean.

To cite just one example, redis is widely considered excellent software, but much of its documentation is written in a very imperfect English.

[rgbrgb]

They should definitely do some editing. The grammatical errors are kind of off putting, I totally agree. That said there's a very clear value prop/use case and clear, concise documentation. You may be getting downvoted because your language was rather harsh.

[tolitius]

Раз ты так хорошо шаришь в английской грамматике, и тебя так напрягает нехватка запятых и дефисов, подскажи как лучше сформулировать и "пруфридать" вот это самый комментарий, или... у тебя эта самая пустота в одной из частей твоего, грамматически заточенного мозга (там, кстати, дефис можно поставить) мешает тебе справиться с задачей?

в следующий раз (кстати с заглавной буквы можно начать) перед тем как насилывать свою клаву, лучше пойди на подкурсы русского или китайского или хотя бы того же английского.

очень не сложно оставлять мусорные комментарии, не относящиеся кстати к теме разговора, и называть себя викинг кодером. гораздо сложнее соответствовать своему имени, и "викинговать" архитектуру, код, мысли, философию создания.

если бы в интернете и/или на хакер ньюз была бы общая корзина для мусора, и можно было бы голосовать за вещи которые туда отправляются, можешь расчитывать на мой голос.

hey VikingCoder, I heard you are a fan of grammar? see above? grammar that.

[lutusp]

Crude automatic translation from Google Translate:

Since you're so good rummage in English grammar, and you so annoying lack of commas and hyphens, tell me how to better articulate and "prufridat" here is the comment, or ... you have this same emptiness in one part of your, grammatically sharpened the brain (where, incidentally, you can put a hyphen) prevents you meet the challenge? next time (by the way with a capital letter, you can start) before its nasilyvat Claudia, better go to the podkursy Russian or Chinese, or at least the same English. not very difficult to leave garbage comments not related to the topic of conversation by the way, and call themselves Viking encoder. much more difficult to live up to its name, and "vikingovat" architecture, code, thoughts, philosophy of creation. if the Internet and / or a hacker would Neuse total waste basket, and it was possible to vote for things that go there, you can count on my vote.

Then, in English:

> ... see above? grammar that.

First time I've heard "grammar" used as a verb. :)

[VikingCoder]

It's like none of you people have ever gone through a code review. Cripes.

[Sami_Lehtinen]

Check out this post: https://news.ycombinator.com/item?id=6314628

I know my spoken and written english is far from perfect, but I can live with it.

[StavrosK]

> rethinking primary alghorithmical [sic, should say "algorithm"] constraints

"Algorithm" isn't an adjective. I accept "algorithmical", although it should probably be "algorithmic".

[VikingCoder]

Reread the word, "alghorithmical". It's completely misspelled.

Memory isn't an adjective either, but the phrase "rethinking primary memory constraints" strikes me as perfectly valid. That's why I concluded that "algorithm" would be the most clear word. But yes, I think "algorithmic" would have been fine as well.

[jasonwatkinspdx]

Unfortunately the chosen font renders very poorly (at least for me in chrome).

[thezilch]

  document.getElementById("main").style.fontFamily = "sans-serif";