17

Обновление

Проект «Документация» был закрыт.


Перевод «Warlords of Documentation: A Proposed Expansion of Stack Overflow».


Прошло 7 лет с момента запуска Stack Overflow, за которые было задано 10,000,000+ вопросов. Сложно переоценить то благо, которое было сделано для индустрии, всю ту помощь, что разработчики день за днем предоставляют друг другу, тот вклад в становление новичков специалистами. Тяжело выразить, насколько мы гордимся тем, что сделали вместе (и не просто потому что из поисковой выдачи пропал наш идеологический враг), ведь в самом начале пути никто не мог предположить, что сообщество примет цель “сделать Интернет лучше”.

Последнее время мы спрашиваем себя: “Что еще мы можем сделать, чтобы улучшить жизнь разработчиков в Интернете?”. Давайте вспомним исходную публикацию Джеффа о запуске Stack Overflow:

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

Stack Overflow превзошел все ожидания в достижении этих целей, но все же существует еще одна область, где решения еще нет - документация. Также как вопросы и ответы в 2008 году, документация в 2015 - это то, что ежедневно необходимо каждому разработчику, и то, что, судя по всему, не развивается с 1996. Нам кажется, вместе мы можем сделать ее намного лучше.

Как добавление раздела «документация» на Stack Overflow сможет улучшить документацию?

  1. Документация создается постфактум, во многих случаях лишь для того, чтобы показать, что что-то существует, и лишь с небольшим намеком на качество. Каждый из нас видел предостаточно примеров в свое время. Плохая документация - это плохо Мы можем добавить акцент на качество, проверку и «реальную помощь реальным разработчикам» - как раз то, что всеми будет приветствоваться.

  2. Зачастую документации не хватает примеров или примеры настолько просты, что не отображают реального использования. Поскольку Stack Overflow постоянно пополняется полезными отзывами разработчиков, пишущих реальный код, мы можем значительно улучшить качество примеров в документации и самой документации в целом. Положив руку на сердце, поиск примера кода - уже давно стал повседневным способом использования Stack Overflow.

  3. Большинство создаваемой документации привязано к циклу выпуска продуктов, как результат, она редко обновляется и еще реже бывает завершенной. Идеи коллективного наполнения и совместного редактирования Stack Overflow непременно улучшат ее.

  4. Большое количество документации берет свои начала от Javadocs. Хотя в 96-м это было лучше, чем ничего, тяжело назвать сложившуюся ситуацию «хорошей» в 2015. Мы можем сосредоточиться на предоставлении лучшего опыта пользователя для ведения документации в современном Интернете.

Каким образом добавление «документации» улучшит Stack Overflow?

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

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

  3. Существует много вопросов, причина которых - плохая документация. Если вы видите множество людей, которые задают вопросы про классы Foo и Bar, то документация про Foo на Stack Overflow сможет исправить множество проблем с Bar и искоренить проблему многократно повторяемых одинаковых вопросов.

  4. Небольшая, но реальная возможность предоставить больше свободы в проявлении взаимной помощи. Зачастую мы слышим от разработчиков, которые получили реальную помощь в ответе на Stack Overflow, что они испытывают затруднение в поиске вопроса без ответа, отвечая на который они бы могли в полной мере выразить свою благодарность сообществу. Документация добавляет больше возможностей для благодарности в ответ.

План действий: нам нужна ваша помощь, чтобы сделать документацию возможной

На первом шаге мы хотим поделиться своими “сырыми” идеями о том, как может выглядеть и работать раздел «документация» на Stack Overflow, и с удовольствием выслушать ваши отзывы. Подчеркнем, идея все еще очень “сырая”, но, по нашему опыту, большинство успешных идей, реализованных на Stack Overflow, изначально исходили от сообщества, поэтому мы бы хотели предоставить вам возможность принять участие как можно раньше.

Вторым шагом будет закрытая бета, где мы сломаем все, а команда разработчиков будет лить слезы будем тестировать инструменты и процессы, но не на Stack Overflow. Вы можете найти форму регистрации для закрытой беты ниже. Закрытая бета будет запущена традиционно в течение шести-девяти недель.

Потом случилось чудо

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

Неудача, как обычно, один из вариантов

Но нам кажется, что игра стоит свеч. Интересно? Тогда голосуйте за это сообщение и регистрируйтесь для участия в бете. Не нравится? Голосуйте против. Появились вопросы или комментарии? Далее вы найдете расширенное описание, но в любом случае мы с нетерпением ждем ваших отзывов, мы очень хотим услышать, что думаете именно Вы! В конце концов, Stack Overflow - это Вы.

Как документация будет работать*

* как нам кажется

Хорошо знакомые сообществу Stack Overflow метки, такие как или , могут быть ассоциированы с документацией, созданной для них. Документация разбита на страницы, называемые публикациями.

Страница публикации

Публикации всегда имеют примеры и пояснения, остальные разделы необязательны.

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

Мы создали новый редактор, так как использовать текущий для написания публикаций было бы сложно, поскольку ожидается, что публикации будут намного объемнее, чем типичный вопрос или ответ.

Новый редактор

Вы можете редактировать отдельные разделы и примеры, видя предварительный результат в реальном времени. Внесенные изменения будут автоматически сохраняться как черновики. Конечно же, мы продолжим использовать MarkDown и prettify для форматирования и подсветки синтаксиса.

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

Поиск существующего запроса

Изначально участник выполняет поиск существующих запросов и голосует «за», и только если он не может найти нужный, он сможет запросить его.

Отправить запрос на публикацию

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

Для размещенных публикации доступны голосования, тревоги и отзывы. В общем-то, они похожи на существующие.

Все действия (запросы, ожидания изменения, тревоги, голоса и т. д.) собраны в панель просмотра для пользователей, которые желают внести свой вклад.

Панель вклада

Каждое “более” и разделы ведут на полный список, также как и в учётной записи пользователя.

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

FAQ

  1. Как будет работать репутация?

    • Участник получает балы репутации после проверки внесенных им изменений в документацию. На проверку идут: описания, предлагаемые правки или голоса. Зарабатываемая при написании документации репутация будет добавляться к существующей (то есть не будет двух раздельных цифр). Откровенно говоря, мы все еще работаем над деталями.

    • На наш взгляд, система репутации раздела документации в некотором смысле будет основана на репутации, аналогично разделу вопросов и ответов.

  2. Какую документацию можно добавлять?

    • На наш взгляд, «все, что вы используете для написания кода», является исходным ориентиром, но итоговое решение этого вопроса мы совершенно точно примем всем сообществом, аналогично тематике сайта вопросов и ответов.

    • На время беты мы постараемся остановиться на известных, широко используемых проектах, так как планируем опробовать основной функционал и убедиться, что все процессы и инструменты работают, как задумывалось. В случае успеха документировать можно будет любую тему, о которой есть вопросы и ответы.

  3. Что следует документировать?

    • Все, что мы можем сделать качественно лучше. Если проект уже имеет документацию удивительно хорошего качества, которою очень просто найти и легко использовать, нет нужды дублировать ее на Stack Overflow. Наша задача в исправлении проблемных мест, а не копировании.
  4. Где проходит граница между вопросом и запросом публикации?

    • Публикация более общая, чем вопрос. По правде говоря, мы ожидаем, что большинство «заданных» вами запросов публикаций были бы закрыты в виде вопросов как «всеобъемлющие».

    • Публикация должна иметь множество примеров, таким образом, запрос, решением которого будет публикация, содержащая единственный пример (то есть пример кода), скорее всего слишком узок.

  5. Призываете ли вы импортировать существующую документацию?

    • Нет. Мы надеемся, что сможем улучшить документацию, а не просто перенести ее на stackoverflow.com.
  6. Какую лицензию будет иметь документация?

Зарегистрируйтесь на бету!

Для вашего участия, нам необходимо получить от вас следующее.

  • Вашу электронную почту.
  • Ссылку на вашу учётную запись Stack Overflow.
  • Список из 2-5 меток, по которым вы бы хотели составлять документацию.

Пожалуйста, выбирайте метки на первых двух страницах раздела популярные метки, которые имеют особенно активное сообщество пользователей, такие как , , or . Таким образом мы сможем проверить всю систему в реальных условиях вместе с множеством разработчиков на стадии закрытой беты.

Зарегистрируйтесь и помогите сделать документацию лучше!


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

11
  • 7
    Думаю, это начинание может быть очень полезно именно в локализованных версиях. Скажем, официальная документация по Java весьма и весьма хороша, дополнять там особо нечего. Если я вижу ошибку или неточность, я разработчикам Java лучше сообщу, чем буду где-то исправленную копию плодить. А вот полного перевода на русский, конечно, нету. Commented 8 сент. 2015 в 15:38
  • 1
    Зарегистрировался, но в ответ ничего не получил. Так и должно быть?
    – Nick Volynkin Мод
    Commented 8 сент. 2015 в 16:39
  • @NickVolynkin На сколько я понимаю текущий процесс, ребята собирают учетные записи, затем, как только закрытая бета будет доступна, они вручную активируют доступ для тех, кто откликнулся.
    – Nicolas Chabanovsky СотрудникМод
    Commented 8 сент. 2015 в 17:02
  • @NicolasChabanovsky: у нас такого не будет?
    – Nick Volynkin Мод
    Commented 8 сент. 2015 в 17:03
  • Непременно будет, но после того, как система в базовом виде пройдёт проверку.
    – Nicolas Chabanovsky СотрудникМод
    Commented 8 сент. 2015 в 17:07
  • 3
    Не вижу смысла в [featured] здесь, это только привлекает внимание к тому, что для нас эта возможность пока недоступна. Участники, которые способны писать документацию на английском, наверняка увидят эту публикацию на Мете En.SO.
    – Nick Volynkin Мод
    Commented 11 сент. 2015 в 20:38
  • 1
    @NickVolynkin Данная публикация призвана рассказать сообществу о нововведениях движка, которые они могли пропустить, и при желании принять участие в тестировании. Функция будет доступна русскоязычному сообществу, как только пройдет проверку. Все же, я убрал featured.
    – Nicolas Chabanovsky СотрудникМод
    Commented 11 сент. 2015 в 22:55
  • Хьюстон? Вы там живые? Что с доками, Док?
    – DaemonHK
    Commented 28 нояб. 2017 в 3:45
  • @DaemonHK Большое спасибо за напоминание. Обновил публикацию.
    – Nicolas Chabanovsky СотрудникМод
    Commented 29 нояб. 2017 в 9:28
  • 1
    @NicolasChabanovsky очень жаль что закрыли(( хотя оно и понятно, это титанический труд
    – DaemonHK
    Commented 29 нояб. 2017 в 9:59
  • @DaemonHK дело не столько в титаническом труде, а скорее в том, что предложенное решение не решало проблему документации, но при этом добавляло новых проблем. Почитайте вопрос, приведённый наверху, там рассказывается, как всё полетело кувырком. Может, потом попытаются предложить новое решение. Но это будет уже "когда-нибудь".
    – user181100
    Commented 29 нояб. 2017 в 10:28

0

Войдите, чтобы ответить на этот вопрос.

Посмотрите другие вопросы с метками .