Stackoverflow объявил о запуске нового амбициозного проекта: центра документации по всем существующим технологиям.
Предполагается, что для каждого тега, существующего в Стеке, можно будет создать раздел документации, и в этом разделе размещать темы, аналогичные существующей парадигме вопрос-ответ, но являющиеся разделами документации.
Может оказаться, что Stack станет для open-source-сообщества такой же стандартной платформой для документации, как, скажем, Github для исходного кода.
По задумке Джеффа, Кевина и других основателей сайта, это позволит пользователям самим создавать более качественную документацию, чем это часто предоставляют авторы той или иной технологии.
Тогда программисты вообще не смогут покинуть сайт Stack, где они и так проводят много времени, решая свои повседневные задачи.
Пользовательская корректура, голосование, примеры кода, единый поиск, мотивация репутацией — есть надежда, что всё это поможет создать на порядок более качественную и востребованную документацию, причём для всех технологий сразу.
Авторы особенно полагаются на примеры кода.
Действительно, количество полезных примеров кода в стеке превышает любую официальную документацию по любой технологии.
Это связано с тем, что писать примеры достаточно сложно; каждый требует много вдумчивости и времени.
Только многие тысячи пользователей могут написать столько примеров, сколько в стеке, и даже хорошая команда документации не сможет конкурировать с хорошо организованной толпой.
Часто при выпуске продукта и публикации документации количество полезных примеров кода остается неизменным, по крайней мере, до следующей версии продукта, когда разработчики обновляют документацию.
Стек логически предполагает, что постоянно обновляемая документация может сделать жизнь разработчиков лучше.
Основатели также утверждают, что устарел сам формат документации, используемый в большинстве проектов, то есть сам пользовательский интерфейс.
Большинство систем документации языков программирования, библиотек и API унаследуют идеи Javadocs двадцатилетней давности.
Ссылки в таких системах обычно локальные и теряются с версиями.
Команда Stack обещает решить обе проблемы, сделать вечные глобальные ссылки и современный пользовательский интерфейс, унаследованный от интерфейса основного сайта вопросов и ответов и проверенный миллионами пользователей.
Они грозят, что их Yuai/YuiX будут лучшими в мире.
На самом деле люди в Стеке очень практичны, у них соображения совсем другого порядка.
Проблема, которая постоянно мучает пользователей и владельцев Стека, заключается в том, что он слишком широк и не по теме.
В комментариях уже много лет идут баталии из-за того, что люди хотят задать «общие» вопросы, например «что посоветуете прочитатьЭ» Был создан отдельный хаб для программистов, но он не пользуется особой популярностью и поток «не по теме» и «бабам» не ослабевает. Так вот: есть надежда, что большая часть этих вопросов уйдет в документацию, а не будет с ними бороться, они станут полезной частью сети.
Сами статьи на Stackoverflow теперь смогут ссылаться на документацию по самому стеку.
Это решит очень серьезную проблему: битые ссылки.
Ссылки на документацию присутствуют в огромном количестве вопросов и ответов, причем процент из них «битых» и устаревших с годами растет, поскольку официальная документация постоянно мутирует по содержанию или мигрирует по ссылкам.
По статистике, многие вопросы по стеку, как правило, возникают только потому, что в официальной документации нет или некачественная информация по определенной теме.
Более того, такие вопросы можно задавать десятки и сотни раз, и их приходится удалять снова и снова, тратя время и ресурсы модераторов и сообщества в целом.
Есть надежда, что в таких случаях сообщество отреагирует созданием соответствующих статей в доках и поток этих дублей сократится, высвободив творческие силы сообщества для более полезных дел.
Еще одним важным вопросом, который в результате может улучшиться, является способность быть полезным.
В настоящее время многие люди, использующие стек, хотят написать что-то полезное для других, что-то, в чем они очень хороши, но не могут, потому что не могут найти подходящие вопросы или не хотят участвовать в гонке ответов.
.
Знаете, в стеке так и есть, в погоне за репутацией люди спешат ответить как можно быстрее, часто используя различные ухищрения, чтобы вывести свой ответ в топ.
Теперь вы можете потихоньку создавать темы для документации по огромному количеству тем и, кстати, получать голоса за свою репутацию.
Учредители до сих пор не уверены в успехе этого начинания; многие амбициозные проекты терпят неудачу в этом мире.
Поэтому стартуют медленно, пока открыта только приватная бета, в которой тестируются все технологии: формы, поиск, отображение и так далее.
Пока идея такая: берется тег из существующих на Stackoverflow и для него создаются страницы, официальное название которых — «темы».
Каждая тема имеет название, примеры и примечания, а также дополнительные разделы, которых может быть сколько угодно.
Основной акцент, конечно, делается на примерах.
Так как наглядный пример, иллюстрирующий тему, — это то, что разработчик ищет в документации (и не находит в большинстве случаев, отсюда и популярность стека).
Примеры могут быть «свернутыми» (свернутыми); глобальные ссылки могут вести не только на всю тему, но и на отдельный пример.
В целом редактор будет новый, хотя и будет похож на редактор анкеты-ответа.
Макдаун, освещение, увеличенное окно.
Помимо тем, кстати, можно будет создавать запросы (запросы), за них можно будет голосовать, а топовые запросы должны вызывать у посетителей желание писать темы о них.
Как все это конкретно повлияет на репутацию, пока не ясно.
Однако уже сейчас понятно: репутация вопросной части сайта и репутация в доках будут общими! Конечно, имеет место смешение мотивов.
С одной стороны фаундеры кидаются фразами типа «одно кольцо(документы), чтобы ими всеми управлять», с другой стороны говорят, что не надо конкурировать с хорошей существующей документацией, а только работать там, где нет качественной документации.
.
Все это вызывает множество вопросов у людей.
Возникает другой вопрос: куда мне теперь размещать свои вопросы и проблемы, в запрос новой темы или в старую анкету? Это может вызвать большую путаницу, например, «как добавить две строки в Java» — это в разделе «Вопросы и ответы» или это запрос на новую статью в документе? Пока не ясно, хотя гайды (правила) на эту тему публикуются.
Импорт статей из существующей документации запрещен.
Лицензионная политика есть, но я не буду ее здесь обсуждать, так как статья ознакомительная.
Завязалась широкая дискуссия, и я приведу ряд вопросов, получивших широкий резонанс.
Спрашивают: вы говорите, что если у проекта хорошая документация, то нет необходимости создавать доки для этого проекта в стеке, а что, если доки были созданы в стеке, а потом у проекта появилась своя крутая документация? Будет ли в этом случае удалена документация по стеку? Вопрос непростой, но Кевин объяснил его логично: давайте создадим системы голосования, пусть сообщество решит, что стереть, а что оставить.
Другой вопрос, что делать в таких системах, как .
NET, где версий много и у каждой своя большая документация.
Ответ в том, что версии технологий тоже будут учитываться специальными средствами! Пока нет более подробной информации о том, как именно это произойдет. Наибольшую кучу плюсов получил комментарий (хотя технически это ответ) человека, разместившего комикс из трех скриншотов, в первом он набрал в гугле «node.js write file», а первую ссылку из сверху ведет в Стек, во второй - открытая по этой ссылке страница, где сразу появляется нужный пример записи в файл, а на третьем - страница официальной документации Node.js, где есть список поддерживаемых функций типичен для этого ресурса и совершенно непонятно, что читать дальше.
То есть люди ищут примеры.
Однако это само по себе не доказывает необходимость нового сайта.
Люди очень обеспокоены тем, что произойдет путаница между официальной документацией и документацией по стеку.
Некоторые считают, что это будет «выживание сильнейшего», другие думают, что официальная документация будет только для заядлых людей и тех, кто пишет документацию для стека, а большинство будет пользоваться последними, причем сами основатели стека считаю, что лучше всего официально перенести официальную документацию на платформу Stack! Наличие единого, глобального, проверенного пользовательского интерфейса и огромной публичной корректуры и редактирования должно быть удобно для создателей технологий, не так ли? Вероятно, первыми этой возможностью воспользуются создатели проектов с открытым исходным кодом.
Некоторые опасаются, что концентрация всей документации на одном ресурсе может превратить Stack в корпорацию зла.
Но другие отвечают, что по сути стек — это просто хостинг, вся власть на нем принадлежит обществу и механизмам голосования и непонятно, чем это может быть злом.
Многие считают, что документация — это слишком широкое понятие, и предлагают Stack сосредоточиться исключительно на примерах.
Это тоже вызывает серьезные вопросы, ведь редкий пример сделан вообще без какой-либо текстовой поддержки.
Кроме того, понятно, что хотя примеры и являются убийственной фишкой нового проекта, но есть и оффтопы и аутсайдеры, битые ссылки, возможность внести свой вклад для тех, кто на данный момент не может, и другие вполне практичные особенности.
Еще предлагают сделать сайт с туториалами и хаутой.
Люди также обеспокоены тем, что документация, особенно официальная, должна восприниматься как истина в последней инстанции, а на Стеке она сама станет предметом обсуждения, и где гарантии, что она будет соответствовать действительности, особенно когда разработчики пишут одно , на самом деле другое, и писать код все равно рекомендуется по документации, даже если известно, что, например, в компиляторе есть ошибка.
На что люди отвечают саркастической реакцией, справедливо указывая на то, что официальной документации, не содержащей ошибок, путаницы, битых примеров и так далее, мало.
Один человек воспринял положительную сторону, сказав что-то вроде: если вы хотите, чтобы документация была чем-то вроде Библии, вы можете установить MSDN с компакт-диска.
Я получил массу плюсов от комментария о том, что куча разработчиков, ползающих по сайту (вспомнил пресловутых воображаемых обезьян за машинкой, пишущих «Войну и мир»), никогда не создадут качественную документацию, потому что этим должны заниматься профессионалы умеющие все это правильно структурировать, формализовать, осознающие сложность и ответственность задачи.
Помимо прочего, документация является источником стиля программирования и шаблонов решения проблем, и только профессиональные составители документов, работающие в тесном контакте с разработчиками этой технологии, могут создавать документы, которые не только показывают, как можно решить проблему, но и объясняют, как она может быть решена.
должна быть решена с точки зрения разработчиков технологий.
Хотя на этот вопрос не было популярного ответа, некоторые отмечали, что когда тысячи программистов используют технологию и решают всевозможные вопросы, связанные с ней, они создают доки именно такие, какие нужны другим пользователям этой технологии, и это совсем не проблема.
тот факт, что «это ваши».
«Профессиональные писатели, работающие в тесном контакте с разработчиками», действительно необходимы.
Возможно, этот вопрос больше волнует самих профессиональных копирайтеров, ведь их много и они получают зарплату.
Кстати, их работа может и не исчезнуть, за них просто будут платить».
сидя на стопке».
Один человек меня очень порадовал, приведя примеры оффтопиков, которые постоянно убиваются в стеке, но которые «должен знать каждый», и которым должно найти место на сайте, и которые, кстати, вызывают множество вопросов этого могло не быть.
Люди должны знать эти основные вещи: «никогда не используйте scanf», «правила псевдонимов на основе типов асимметричны» (сложно перевести) и «напрасно вы пытаетесь решить эту проблему с помощью оболочки».
сценарий».
Люди, писавшие документацию для open-source проектов, говорили в том духе, что писать официальную документацию гораздо приятнее, чем для «каких-то форумов и вики», пытаясь привести различные квазирациональные аргументы, например, о том, что авторы open-source исходные проекты любят, когда к ним обращаются за разъяснениями вопросов.
Но меня почему-то это не особо убеждает. Официальная ветка обсуждения на английском языке есть на Meta, к участию приглашаются все желающие: Meta.stackoverflow.com/questions/303865/warlords-of-documentation-a-propose-expansion-of-stack-overflowЭcb=1 Такая ситуация, ждем развития событий.
Для себя я еще не решил, хорошо это или плохо, но одно могу сказать точно, мне очень интересно, что (не) из этого выйдет. Было бы интересно сравнить приведенные выше мнения англоязычного сообщества с тем, что думает наше русскоязычное сообщество, не стесняйтесь оставлять свои комментарии! И напоследок, дорогие читатели, предлагаем вам небольшой опрос: В опросе могут участвовать только зарегистрированные пользователи.
Войти , Пожалуйста.
Что вы думаете об этом? 65,3% Классная идея! 1054 4.03% Ерунда.
65 4.65% Я не по теме 75 26.02% Подождем и посмотрим 420 Проголосовали 1614 пользователей.
310 пользователей воздержались.
Теги: #stackoverflow #программирование
-
Как Я Помог Создать Хакатон В Красной Поляне
19 Oct, 24 -
Ipicture Скриншутер
19 Oct, 24
