Плохая и хорошая документация языка

Язык Go не отличается красотой. Кто-то называет его «намеренно простым», кто-то уродливым. Но с чем у Go действительно всё классно — так это с документацией. Там много хорошего, но вот главное, на мой взгляд:

1. A Tour of Go — интерактивное введение в язык.
2. Effective Go — книга о том, как писать идиоматичный код на Go.
3. Ссылки из документации на исходники каждой функции стандартной библиотеки (например, Max).

Для сравнения я взял топ-10 языков из StackOverflow Developer Survey и посмотрел, как у них дела с этими тремя пунктами.

1. JavaScript

У языка даже своего сайта нет ツ Есть миллион обучалок, но единого авторитетного источника — нет. Документация по языку есть только благодаря Мозилле. Ссылок на исходники нет, конечно. Зато по каждой функции есть интерактивный пример, это отлично.

2. SQL

Всё как у JS, только хуже — в мире SQL не нашлось своей Мозиллы, которая бы сделала документацию с примерами. Где свой SQL получали, там и ищите.

3. Python

Первый язык в топе с собственным сайтом. Есть ссылка Get Started, но дальше разбегаются глаза — что выбрать? Вместо рекомендованной авторами базовой обучалки вываливают на новичка простыню ссылок. Официальный туториал найти можно только каким-то нетривиальным способом. Интерактива нет. Незачёт.

Исходников отдельных функций нет, исходники модулей — только если они написаны на Python (например, для heapq исходники есть, а для itertools — нет).

4. Java

Язык принадлежит компании Оракл, этим всё сказано. Заходите на официальный сайт посмеяться.

Если пройтись по ссылкам дальше, попадаешь на страницу Learn Java Skills, где Оракл любезно предложит прикупить семинар. Если ну очень постараться, можно набрести на документацию по языку, даже с примерами. Странно, что за доступ не надо платить или хотя бы регистрироваться в Oracle Developer Network — надеюсь, эту недоработку скоро исправят.

5. Bash

Не ожидал, но у него есть сайт и документация. Спасибо и на том.

6. С#

Первый язык родом из нового тысячелетия в списке. Есть интерактивный туториал, тур по языку и руководство разработчика. Неплохо! В документации есть интерактивные примеры, а вот ссылок на исходники нет.

7. PHP

Первое, что встречает на официальном сайте — Please DO NOT use this version in production, it is an early test version. Спасибо, да. Я бы вообще сделал DO NOT use this in production официальным слоганом языка. Кхм, пардон, отвлёкся. Есть неинтерактивная обучалка, неплохая документация со статическими примерами и комментариями сообщества, и, неожиданно — аж целая книга PHP at the Core: A Hacker’s Guide.

8. TypeScript

Новейший язык, 2012 года выпуска. Несколько введений, местами интерактивные. Подробный учебник, который начинается как интерактивный, но быстро превращается в статический (как так?). Ссылок на исходники нет, но они особо и не нужны — у тайп-скрипта нет собственной стандартной библиотеки.

9. C++

Есть интерактивный тур по языку! Шучу, конечно. Тур выложен в PDF, что тут скажешь. Зато есть Core Guidelines о том, как писать правильный код.

10. C

Сайта нет, ничего нет, населена роботами.

⌘ ⌘ ⌘

Счёт 10-0 в пользу Go.