Stackoverflow объявили о запуске нового амбициозного проекта: документационном хабе для всех существующих технологий. Предполагается, что для каждого существующего на Стеке тэга можно будет создать раздел документации, и в этом разделе постить топики, похожие на существующую парадигму вопрос-ответ, но являющиеся разделами документации. Возможно получится, что Стек станет для опен-сорсного комьюнити такой-же стандартной площадкой для документации, как, скажем, Гитхаб для исходников.

По задумке Джеффа, Кевина и других основателей сайта, это позволит пользователям самим создавать более качественную документацию, чем зачастую предоставляют авторы той или иной технологии. Тогда программисты смогут вовсе не покидать сайт Стека, где они и так проводят много времени решая свои ежедневные проблемы. Пользовательская вычитка, голосование, примеры кода, единый поиск, мотивация репутацией — есть надежда, что всё это поможет создать на порядок более качественную и востребованную документацию, причём для всех технологий сразу.

Авторы особенно уповают на примеры кода. Действительно, количество полезных примеров кода на Стеке превосходит любую официальную документацию по любой технологии. Это связанно с тем, что писать примеры довольно сложно, каждый требует большой вдумчивости и времени. Написать столько примеров, как на Стеке могли только многие тысячи пользователей, а даже хорошая документирующая команда в этом не сможет состязаться с хорошо организованным краудом.

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

Ещё основатели утверждают, что сам формат документации используемый в большинстве проектов устарел, то есть сам пользовательский интерфейс. Большинство систем документации языков программирования, библиотек, API унаследуют идеи Javadocs двадцатилетней давности. Ссылки в таких системах как правило локальны и теряются с версиями. Стековцы обещают решить обе проблемы, сделать вечные глобальные ссылки и современный пользовательский интерфейс наследуемый от интерфейса основного сайта вопросов-ответов и обкатываемый миллионами пользователей. Грозятся, что их юай/юикс будет лучшим в мире.

На самом деле люди в Стеке очень практичные, у них есть соображения совершенно другого порядка. Постоянно мучающая пользователей и владельцев Стека проблема это too broad и офф-топик. В комментариях годами идут баталии потому, что людям хочется задавать воопросы «вообще», например «что посоветуете почитать». Был создан отдельный хаб programmers, но он не особо популярен и поток «офф-топиков» и «ту-броадов» не ослабевает. Так вот: есть надежда, что большая часть таких вопросов уйдёт в документацию вместо того чтобы с ними бороться они станут полезной частью сети.

Сами статьи на Стековерфлоу смогут теперь ссылаться на документацию на самом Стеке. Это решит очень серьёзную проблему: битые ссылки. Ссылки на документацию есть в огромном количестве вопросов-ответов, и процент их «битости», устарелости с годами растёт, поскольку официальная документация постоянно мутирует по содержанию или мигрирует по ссылкам.

По-статистике множество вопросов на стэке, вообще, возникают только из-за того, что в официальной документации нет или некачественная инфа по некоторой теме. Причём, такие вопросы могут задаваться десятки и сотни раз, и их приходится удалять снова и снова, расходуя время и ресурсы модераторов и комьюнити в целом. Есть надежда, что в таких случаях сообщество отреагирует созданием соответствующих статей в доках и поток этих дубликатов сократится высвободив творческие силы комьюнити на более полезные дела.

Ещё важнейший вопрос, который возможно улучшится в результате — это возможность приносить пользу. Сейчас очень много людей пользующихся Стеком хотят написать что-то полезное для других, в чём они класно разбираются, но не могут, потому, что не могут найти подходящих вопросов или не желают учавствовать в гонке ответов. Знаете, на Стеке это есть, в погоне за репутацией люди бросаются отвечать с максимальной скоростью применяя зачастую разные трюки для выведения своего ответа в топ. Теперь можно будет не торопясь создавать топики для документации по огромному количеству тем и, кстати, получать голоса в репутацию.

Основатели всё ещё не уверены в успехе этого начинания, немало амбициозных проектов проваливается в этом мире. Поэтому они начинают не спеша, пока открыта только приватная бета, на которой обкатываются все технологии: формы, поиск, отображение и так далее.

Пока идея такая: берётся тэг из существующих уже на Стековерфлоу и к нему создаются странички, официальное название которых «топики». Каждый топик имеет заглавие, примеры и примечания, а так-же опциональные разделы, которых может быть сколько угодно. Основной упор делается, конечно, на примеры. Поскольку именно понятный, иллюстрирующий тему пример — это то, что разработчик ищет в документации (и не находит в большинстве случаев, отсюда популярность Стека).

Примеры можно «схлопывать» (коллапсить) глобальные ссылки могут вести не только на весь топик, но и на отдельный пример. Вообще редактор будет новый, хотя и похож на редактор вопросника-ответника. Макрдаун, подсветка, увеличенное окно. Кроме топиков, кстати, можно будет создавать запросы (реквесты), за них можно голосовать и топовые реквесты должны вызывать желание писать по ним топики у посетителей. Как это всё будет конкретно сказываться не репутации ещё не ясно. Однако уже ясно: репутация вопросной части сайта и репутация в доках будет общей!

Конечно, имеется путаница в мотивах. С одной стороны основатели бросаются фразами в духе «one ring(docs) to rule them all», с другой стороны говорят, что не надо соревноваться с хорошими существующими документациями, а только работать там, где нет качественных документаций. Всё это вызывает у народа немало вопросов.

Ещё вызывает вопрос, куда постить теперь свои вопросы и проблемы, в новый реквест топика или старый вопросник? Это может вызвать немалую путаницу, например «как сложить две строки на Джаве» это куда, в вопросы-ответы или это реквест на новую статью в доке? Пока не ясно, хотя пушутся гайды (правила) на эту тему.

Импортирование статей из существующих документаций запрещено. Есть лицензионная политика, но здесь я её не буду обсуждать, поскольку статья вводная.

Развернулась широкая дискуссия, приведу ряд вопросов котоые получили широкий резонанс.

Спрашивают: вы говорите, что если у проекта есть хорошая документация, то не надо делать доки для этого проекта на стэке, но как быть в случае если доки были созданы на стэке, а потом у проекта появилась своя крутая документация? Будет ли в таком случае стёрта документация стэка?

Вопрос каверзный, но Кевин логично объяснил: что, мол, создадим голосовательные системы, пусть сообщество решает, чего стирать, а чего оставлять.

Другой вопрос, что делать в системах подобных .NET, где множество версий и под каждую своя крупная документация. Ответ такой, что версии технологий тоже будут учтены специальными средствами! Пока более подробной инфы, о том, как именно это будет — нету.

Самую большую кучу плюсов получил комментарий (хотя технически это ответ) человека который запостил комикс из трёх скриншотов, на первом он набрал в гугле «node.js write file», и первая ссылка сверху ведёт на Стек, на втором страничка открытая по этой ссылке, где сразу бросается искомый пример записи в файл, а на третьем страничка официальной документации по Node.js, где типичный для этого ресурса список поддерживаемых функций и совершенно не понятно что читать дальше. То есть люди ищут примеры. Впрочем само по себе это не доказывает необходимости нового сайта.

Люди очень переживают, что возникнет путаница между официальными документациями и документацией на Стеке. Некоторые считают, что это будет «выживет сильнейший», другие думают, что официальная документация будет только для хардкорщиков и тех, кто пишет доки для Стека, а большинство будет пользоваться последней, а сами основатели Стека полагают, что лучше всего официально мигрировать официальные доки на платформу Стека! Иметь единый, глобальный, обкатанный пользовательский интерфейс и гигантскую общественную вычитку и правку должно быть удобно создателям технологий, разве нет? Создатели open-source проектов, наверняка первыми воспользуются такой возможностью.

Некоторые переживают, что концентрация всей документации на одном ресурсе, может превратить Стек в Корпорацию Зла. Но другие отвечают, что в сущности Стек это лишь хостинг, вся власть на нём принадлежит обществу и механизмам голосования и не понятно, как это может быть злом.

Многие считают, что документация это слишком обширное понятие и предлагают Стеку сконцентрироваться исключительно на примерах. Это тоже вызывает серьёзные вопросы, ведь редкий пример обходится совсем без текстового сопровождения. К тому-же ясно, что хотя примеры это киллер-фича нового проекта, но есть же и офф-топики и ту-броады, битые ссылки, возможность контрибутить для тех кто сейчас не может и прочие совершенно практические фичи.

Предлагают ещё сделать сайт для туториалов и хауту.

Ещё люди переживают, что документация, особенно официальная, должна восприниматься как истина в последней инстанции, а на Стеке она сама станет предметом дискуссии, и где гарантии, что она будет соответствовать действительности, особенно, когда разработчики пишут одно, в реальности другое, а писать код всё равно рекомендуется по документации, даже если известно, что, например, в компиляторе косяк. На что народ отвечает сакразмом, справедливо указывая, что мало найдётся официальной документации в которой не было бы ошибок, путанницы, неработающих примеров и так далее. Один человек нахватал плюсов сказав нечто вроде того, что, мол, если вам нравится когда документация это нечто вроде Библии, можете установить MSDN с компакт-диска.

Много плюсов получил комментарий о том, что куча девелоперов ползающих по сайту (мне вспомнились пресловутые воображаемые обезьянки у пишущей машинки пишущие «Войну и мир») никогда не создадут качественной документации, потому что этим должны заниматься профессионалы, которые знают, как это всё правильно структурировать, оформлять, осознающие всю сложность и ответственность задачи. Кроме прочего, документация является источником программерского стиля и паттернов решения проблем, и создать такие доки которые не просто показывают, как можно решить проблему, но объясняющие как её решать положено с точки зрения разработчиков технологии могут только профессиональные докописатели работающие в тесном контакте с разрабами данной технологии. Хотя популярного ответа на этот вопрос не нашлось, но некоторые указали, что когда тысячи программистов пользуются технологией и решают всякие вопросы с ней связанные, то они создают доки как раз такие как и нужны другим пользователям данной технологии и совершенно не факт, что «эти ваши профессиональные писатели в тесном контакте с разработчиками» действительно необходимы. Возможно этот вопрос больше беспокоит самих профессиональных докописателей, ведь их очень много и они получают деньги. Кстати, их работа может не исчезнуть, им просто будут платить за «сидение на Стеке».

Один человек меня очень порадовал приведя примеры офф-топиков которые постоянно убиваются на Стеке, но которые «должен знать каждый», и которым надо-бы найти место на сайте, и которые, кстати, приводят к множеству вопросов которых бы могло и не быть, знай люди эти элементарные вещи: «никогда не используйте scanf», «the type-based aliasing rules are asymmetric» (затрудняюсь перевести) и «зря вы пытаетесь решить эту проблему шелл-скриптом».

Люди, писавшие доки для открытых проектов высказывались в духе, писать официальные доки гораздо приятнее, чем для «каких-то там форумов и вики», пытаясь приводить разные квази-рациональные доводы, например, что авторы открытых проектов любят, когда с ними связываются для уточнения вопросов. Но как-то это меня не очень убеждает.

Официальная ветка обсуждения на английском языке находится на Мете, все желающие приглашаются принять участие: meta.stackoverflow.com/questions/303865/warlords-of-documentation-a-proposed-expansion-of-stack-overflow?cb=1

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