Обновление
Проект «Документация» был закрыт.
Перевод «Warlords of Documentation: A Proposed Expansion of Stack Overflow».
Прошло 7 лет с момента запуска Stack Overflow, за которые было задано 10,000,000+ вопросов. Сложно переоценить то благо, которое было сделано для индустрии, всю ту помощь, что разработчики день за днем предоставляют друг другу, тот вклад в становление новичков специалистами. Тяжело выразить, насколько мы гордимся тем, что сделали вместе (и не просто потому что из поисковой выдачи пропал наш идеологический враг), ведь в самом начале пути никто не мог предположить, что сообщество примет цель “сделать Интернет лучше”.
Последнее время мы спрашиваем себя: “Что еще мы можем сделать, чтобы улучшить жизнь разработчиков в Интернете?”. Давайте вспомним исходную публикацию Джеффа о запуске Stack Overflow:
Слишком много информации о программировании стало заложником форумов, она прозябает в виде справки на сайтах или спрятана в книгах так глубоко, что уже никто их не покупает. Мы хотим дать ей свободу! Давайте создадим нечто, что очень просто найти и в чем легко принять участие.
Stack Overflow превзошел все ожидания в достижении этих целей, но все же существует еще одна область, где решения еще нет - документация. Также как вопросы и ответы в 2008 году, документация в 2015 - это то, что ежедневно необходимо каждому разработчику, и то, что, судя по всему, не развивается с 1996. Нам кажется, вместе мы можем сделать ее намного лучше.
Как добавление раздела «документация» на Stack Overflow сможет улучшить документацию?
Документация создается постфактум, во многих случаях лишь для того, чтобы показать, что что-то существует, и лишь с небольшим намеком на качество. Каждый из нас видел предостаточно примеров в свое время. Мы можем добавить акцент на качество, проверку и «реальную помощь реальным разработчикам» - как раз то, что всеми будет приветствоваться.
Зачастую документации не хватает примеров или примеры настолько просты, что не отображают реального использования. Поскольку Stack Overflow постоянно пополняется полезными отзывами разработчиков, пишущих реальный код, мы можем значительно улучшить качество примеров в документации и самой документации в целом. Положив руку на сердце, поиск примера кода - уже давно стал повседневным способом использования Stack Overflow.
Большинство создаваемой документации привязано к циклу выпуска продуктов, как результат, она редко обновляется и еще реже бывает завершенной. Идеи коллективного наполнения и совместного редактирования Stack Overflow непременно улучшат ее.
Большое количество документации берет свои начала от Javadocs. Хотя в 96-м это было лучше, чем ничего, тяжело назвать сложившуюся ситуацию «хорошей» в 2015. Мы можем сосредоточиться на предоставлении лучшего опыта пользователя для ведения документации в современном Интернете.
Каким образом добавление «документации» улучшит Stack Overflow?
Мы постоянно получаем запросы на создание места для размещения общей тематической информации: меньше «прикладной проблемы, которая возникла прямо сейчас», больше «есть ли что-либо, что я могу использовать в данном случае». Нам кажется, «документация» может стать отличным местом для большого количества полезной информации, которую мы до сих пор обходили стороной на протяжении многих лет.
Множество сообщений улучшаются добавлением ссылки на официальную документацию, это означает использование ссылок на сторонние сайты, которые, в некоторых случаях, очень тяжело найти, и более того, они могут не работать. Находить и включать документацию в сообщения будет намного проще, если она будет на Stack Overflow.
Существует много вопросов, причина которых - плохая документация. Если вы видите множество людей, которые задают вопросы про классы
Foo
иBar
, то документация проFoo
на Stack Overflow сможет исправить множество проблем сBar
и искоренить проблему многократно повторяемых одинаковых вопросов.Небольшая, но реальная возможность предоставить больше свободы в проявлении взаимной помощи. Зачастую мы слышим от разработчиков, которые получили реальную помощь в ответе на Stack Overflow, что они испытывают затруднение в поиске вопроса без ответа, отвечая на который они бы могли в полной мере выразить свою благодарность сообществу. Документация добавляет больше возможностей для благодарности в ответ.
План действий: нам нужна ваша помощь, чтобы сделать документацию возможной
На первом шаге мы хотим поделиться своими “сырыми” идеями о том, как может выглядеть и работать раздел «документация» на Stack Overflow, и с удовольствием выслушать ваши отзывы. Подчеркнем, идея все еще очень “сырая”, но, по нашему опыту, большинство успешных идей, реализованных на Stack Overflow, изначально исходили от сообщества, поэтому мы бы хотели предоставить вам возможность принять участие как можно раньше.
Вторым шагом будет закрытая бета, где мы сломаем все, а команда разработчиков будет лить слезы будем тестировать инструменты и процессы, но не на Stack Overflow. Вы можете найти форму регистрации для закрытой беты ниже. Закрытая бета будет запущена традиционно в течение шести-девяти недель.
Или мы ошибаемся. Может так случиться, что «документация» не настолько захватывающая для сообщества, как для нас, или мы не придем к финальному решению. А может быть, мы просто не доберемся и до этого шага.
Но нам кажется, что игра стоит свеч. Интересно? Тогда голосуйте за это сообщение и регистрируйтесь для участия в бете. Не нравится? Голосуйте против. Появились вопросы или комментарии? Далее вы найдете расширенное описание, но в любом случае мы с нетерпением ждем ваших отзывов, мы очень хотим услышать, что думаете именно Вы! В конце концов, Stack Overflow - это Вы.
Как документация будет работать*
* как нам кажется
Хорошо знакомые сообществу Stack Overflow метки, такие как .net или python, могут быть ассоциированы с документацией, созданной для них. Документация разбита на страницы, называемые публикациями.
Публикации всегда имеют примеры и пояснения, остальные разделы необязательны.
Примеры можно сворачивать, на них можно ссылаться. Мы разместили их в верхней части страницы, потому что верим, что они и есть самая полезная информация, котрую вы хотели бы видеть. Мы ожидаем, что публикации будут иметь больше примеров, чем вопросы имеют ответов, так как публикации будут «более общие», чем вопросы.
Мы создали новый редактор, так как использовать текущий для написания публикаций было бы сложно, поскольку ожидается, что публикации будут намного объемнее, чем типичный вопрос или ответ.
Вы можете редактировать отдельные разделы и примеры, видя предварительный результат в реальном времени. Внесенные изменения будут автоматически сохраняться как черновики. Конечно же, мы продолжим использовать MarkDown и prettify для форматирования и подсветки синтаксиса.
Любой, имеющий необходимые привилегии по метке, может создавать или редактировать публикации, а те, у кого привилегий недостаточно, смогут предлагать изменения на проверку я-ля предлагаемые правки. Те, кто сочтут публикацию необходимой, но не будут иметь возможность написать ее самостоятельно, могут запросить создание публикации, используя специальную кнопку «запросить публикацию».
Изначально участник выполняет поиск существующих запросов и голосует «за», и только если он не может найти нужный, он сможет запросить его.
Мы предвидим, что типичный хороший запрос будет меньше типичного вопроса. Обычно хороший вопрос имеет некоторые исследования проблемы, код и список решений, которые задающий уже испробовал. Хороший запрос имеет только обоснование необходимости данной документации. Ввиду этих различий, мы планируем создать минималистичный пользовательских интерфейс по сравнению со страницей задания вопроса.
Для размещенных публикации доступны голосования, тревоги и отзывы. В общем-то, они похожи на существующие.
Все действия (запросы, ожидания изменения, тревоги, голоса и т. д.) собраны в панель просмотра для пользователей, которые желают внести свой вклад.
Каждое “более” и разделы ведут на полный список, также как и в учётной записи пользователя.
Все, что вы видите, находится на очень ранней стадии и, весьма вероятно, претерпит изменения, особенно после того, как мы получи ваши отзывы.
FAQ
Как будет работать репутация?
Участник получает балы репутации после проверки внесенных им изменений в документацию. На проверку идут: описания, предлагаемые правки или голоса. Зарабатываемая при написании документации репутация будет добавляться к существующей (то есть не будет двух раздельных цифр). Откровенно говоря, мы все еще работаем над деталями.
На наш взгляд, система репутации раздела документации в некотором смысле будет основана на репутации, аналогично разделу вопросов и ответов.
Какую документацию можно добавлять?
На наш взгляд, «все, что вы используете для написания кода», является исходным ориентиром, но итоговое решение этого вопроса мы совершенно точно примем всем сообществом, аналогично тематике сайта вопросов и ответов.
На время беты мы постараемся остановиться на известных, широко используемых проектах, так как планируем опробовать основной функционал и убедиться, что все процессы и инструменты работают, как задумывалось. В случае успеха документировать можно будет любую тему, о которой есть вопросы и ответы.
Что следует документировать?
- Все, что мы можем сделать качественно лучше. Если проект уже имеет документацию удивительно хорошего качества, которою очень просто найти и легко использовать, нет нужды дублировать ее на Stack Overflow. Наша задача в исправлении проблемных мест, а не копировании.
Где проходит граница между вопросом и запросом публикации?
Публикация более общая, чем вопрос. По правде говоря, мы ожидаем, что большинство «заданных» вами запросов публикаций были бы закрыты в виде вопросов как «всеобъемлющие».
Публикация должна иметь множество примеров, таким образом, запрос, решением которого будет публикация, содержащая единственный пример (то есть пример кода), скорее всего слишком узок.
Призываете ли вы импортировать существующую документацию?
- Нет. Мы надеемся, что сможем улучшить документацию, а не просто перенести ее на stackoverflow.com.
Какую лицензию будет иметь документация?
- Все ту же самую (Creative Commons Attribution Share Alike) и правила использования сайта, под которыми распространяется существующее содержимое. Документация также будет присутствовать в наших регулярных снимках базы данных, как только мы завершим закрытую бету.
Зарегистрируйтесь на бету!
Для вашего участия, нам необходимо получить от вас следующее.
- Вашу электронную почту.
- Ссылку на вашу учётную запись Stack Overflow.
- Список из 2-5 меток, по которым вы бы хотели составлять документацию.
Пожалуйста, выбирайте метки на первых двух страницах раздела популярные метки, которые имеют особенно активное сообщество пользователей, такие как c#, r, or ios. Таким образом мы сможем проверить всю систему в реальных условиях вместе с множеством разработчиков на стадии закрытой беты.
Зарегистрируйтесь и помогите сделать документацию лучше!
Пожалуйста, обратите ваше внимание, что это очень-очень сырая версия совершенно нового функционала. Для команды разработчиков крайне важны прямые отзывы. Команда мультинациональная, как результат, в ближайшее время принять участие в закрытой бете можно будет только на Stack Overflow на английском, а оставить отзыв на Мета Stack Overflow на английском, соответственно. Пожалуйста, учтите это при регистрации на закрытую бету.