How I Judge the Quality of Documentation

Next time you come across a project documented solely in Lithuanian / Japanese / Swahili, I hope you will refer to http://ericholscher.com/blog/2014/feb/27/how-i-judge-documen... for insight. English is the de-facto language of the Internet (let's not discuss here how damaging that is to English as a language in general). I strongly believe that public-facing software projects should be documented in English first and foremost, with translations to other languages added as resources allow. I work for a small…

Here's a summary: 1. Get a website: don't use a readme on GitHub. 2. Use Prose: don't generate from source, you need more. 3. Give permalinks for citation purposes 4. Your URL should acknowledge the documentation version and language, for future-proofing And now for my own opinion: 1. No, not every project finds it rational to put time into creating a website. Especially if they're small. Sometimes, the time is better spent doing dev work than creating a pretty site…

The part about English is pretty weak. I say this as a non-English native speaker: There is no way you can learn programming and actually be a part of the wider ecosystem without learning English. You can argue that it's a pity (I don't agree), you can argue it's cultural imperialism (I guess I can agree, but it's in a good way), you can argue it's unjust (I agree 100%!). But to lay the blame on the maintainers for every…