4 ms·

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 aesthet

by rgbrgb 13y ago

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 13y ago
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.
- rgbrgb 13y ago
  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.
- dilap 13y ago
  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.
- jasonwatkinspdx 13y ago
  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 13y ago
    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 13y ago
      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 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 13y ago
      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 13y ago
- Sami_Lehtinen 13y ago
  Check out this post: https://news.ycombinator.com/item?id=6314628 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 13y ago
  > rethinking primary alghorithmical [sic, should say "algorithm"] constraints "Algorithm" isn't an adjective. I accept "algorithmical", although it should probably be "algorithmic".
  - VikingCoder 13y ago
    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.
- tolitius 13y ago
  Раз ты так хорошо шаришь в английской грамматике, и тебя так напрягает нехватка запятых и дефисов, подскажи как лучше сформулировать и "пруфридать" вот это самый комментарий, или... у тебя эта самая пустота в одной из частей твоего, грамматически заточенного мозга (там, кстати, дефис можно поставить) мешает тебе справиться с задачей? в следующий раз (кстати с заглавной буквы можно начать) перед тем как насилывать свою клаву, лучше пойди на подкурсы русского или китайского или хотя бы того же английского. очень не сложно оставлять мусорные комментарии, не относящиеся кстати к теме разговора, и называть себя викинг кодером. гораздо сложнее соответствовать своему имени, и "викинговать" архитектуру, код, мысли, философию создания. если бы в интернете и/или на хакер ньюз была бы общая корзина для мусора, и можно было бы голосовать за вещи которые туда отправляются, можешь расчитывать на мой голос. hey VikingCoder, I heard you are a fan of grammar? see above? grammar that.
  - lutusp 13y ago
    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 13y ago
    It's like none of you people have ever gone through a code review. Cripes.
jasonwatkinspdx 13y ago
Unfortunately the chosen font renders very poorly (at least for me in chrome).
- thezilch 13y ago
  document.getElementById("main").style.fontFamily = "sans-serif";

by rgbrgb 13y ago

VikingCoder 13y ago

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.

rgbrgb 13y ago
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.
dilap 13y ago
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.
jasonwatkinspdx 13y ago
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 13y ago
  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 13y ago
    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 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 13y ago
    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 13y ago
Sami_Lehtinen 13y ago
Check out this post: https://news.ycombinator.com/item?id=6314628 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 13y ago
> rethinking primary alghorithmical [sic, should say "algorithm"] constraints "Algorithm" isn't an adjective. I accept "algorithmical", although it should probably be "algorithmic".
- VikingCoder 13y ago
  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.
tolitius 13y ago
Раз ты так хорошо шаришь в английской грамматике, и тебя так напрягает нехватка запятых и дефисов, подскажи как лучше сформулировать и "пруфридать" вот это самый комментарий, или... у тебя эта самая пустота в одной из частей твоего, грамматически заточенного мозга (там, кстати, дефис можно поставить) мешает тебе справиться с задачей? в следующий раз (кстати с заглавной буквы можно начать) перед тем как насилывать свою клаву, лучше пойди на подкурсы русского или китайского или хотя бы того же английского. очень не сложно оставлять мусорные комментарии, не относящиеся кстати к теме разговора, и называть себя викинг кодером. гораздо сложнее соответствовать своему имени, и "викинговать" архитектуру, код, мысли, философию создания. если бы в интернете и/или на хакер ньюз была бы общая корзина для мусора, и можно было бы голосовать за вещи которые туда отправляются, можешь расчитывать на мой голос. hey VikingCoder, I heard you are a fan of grammar? see above? grammar that.
- lutusp 13y ago
  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 13y ago
  It's like none of you people have ever gone through a code review. Cripes.

jasonwatkinspdx 13y ago

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

thezilch 13y ago
document.getElementById("main").style.fontFamily = "sans-serif";