Вчера произошло достаточно значимое событие на рынке разработки. Точнее в сфере поддержки и сопровождении программных продуктов. StackOverflow запустил раздел документация. Почему это важно?
На протяжении последних лет, когда github захватил рынок дистрибуции исходных кодов, проблема документации стояла остро. Не смотря на удобство работы с кодом, github так и не смог предложить достойной системы ведения документации – wiki забрасываются, а вести их через cvs попросту слишком трудоемко. ReadTheDocs попробовавший решить эту проблему, явно не совершил переворота, подойдя к проблеме в лоб. Так же есть gitbook, но и его трудно назвать стандартом.
На сегодня существуют следующие проблемы, с которыми сталкиваются разработчики:
- Отсутствие удобного способа вести многостраничную документацию со сложной навигацией.
- Необходимость взаимодействия множества авторов.
- Отсутствие единого стиля оформления документов. Возьмите туже документацию по Mongoose – раздражающие цвета, бедная подстветка синтаксиса.
- Необходимость выбора места хранения и дистрибуции.
- Проблемы "бумажной" работы сами по себе.
Судя по тому, что предлагает StackOverflow, мы получим интересный инструмент, позволяющий решить вышеперечисленные проблемы и позволяющий сделать ведение документации простым процессом. Из возможностей:
- Совместная разработка с поддержкой сравнений (diff).
- Запрос на создание статьи.
- Голосования за изменения, вместо единого автора.
- Стандартная система поощрения stackoverflow.
Остается надеяться, что в скором времени у нас появится больше качественной документации и муторный и для некоторых неприятный процесс ее ведения наконец-то станет приятным.
Комментарии (52)
rogov_dmitry
22.07.2016 14:59+2Не уверен, что стандартный (ну немножко подпиленный) интерфейс SO идеально подходит для таких вики-доков, но в целом впечатление от нового раздела приятное и многообещающее. Взлетит. :)
vyatsek
22.07.2016 15:05По мне документация это иерархичное описание от простого к сложному, с наличием кросс ссылок, Diff к предыдущей версии. Для меня простым было бы писать в xml или WSWYG, но тот же конфлюенс — убог.
Архитектурно для
Идеально редактируешь у себя на компе, потом commit, и веб сервер уже подхватывает изменения и отображает. Для редактирования нужен редактор, который умеет отображать код как браузер. Все остальное, что пробовал — неудобно.
OlegMax
22.07.2016 16:42Так вроде ReadTheDocs подходит по описанию. Для Markdown разметки полно редакторов/плагинов. Требование обязательно XML как-то странно выглядит.
Lure_of_Chaos
22.07.2016 15:45+1Теперь и на SO можно послать RTFMить
Free_ze
22.07.2016 17:19Да и раньше в гугол бодро посылали. Теперь идти недалеко)
Lure_of_Chaos
23.07.2016 00:44В гугол посылать не много смысла, т.к. он на стековерфловочку и вернет.
Так что да, полезное (пока теоретически) нововведение. Особенно, если дока будет оперативно пополняться теми нюансами, о которых спрашивается.Free_ze
23.07.2016 15:23Ну так вернет вопрошающего на уже существующий ответ) Направить в нужную сторону — уже половина дела.
iqiaqqivik
25.07.2016 10:21+1Я вот люблю специалистов, знающих о предмете понаслышке.
На SO всегда было специальным образом запрещено посылать в гугл и за такие ответы минусуют нещадно. Почитайте правила.Free_ze
25.07.2016 12:29-1Конечно минусуют, кто же додумается писать в ответ то, что им не является? В комментариях — ничего, вполне поддерживают, неоднократно инициировал закрытие вопросов с такой формулировкой.
iqiaqqivik
26.07.2016 10:18Это странно, что удавалось с такой формулировкой инициировать закрытие. SO позиционируется как _база знаний_, посыл в гугл даже за самым тривиальным ответом противоречит логике ресурса. Я лично даже дубликаты закрываю очень осторожно.
vedenin1980
26.07.2016 10:22Когда спрашивают элементарное из разряда "Что такое наследование в ООП" или что-то вида "вот задание домашней работы, напишите её за меня", то в гугл в комментариях посылают часто, более того минусуют тех кто отвечает на подобные вопросы.
iqiaqqivik
26.07.2016 10:43Может быть, я лично никогда не видел минусов за ответы по таким соображениям. Но это очень сильно зависит от рубрики, конечно.
На вопросы типа «Что такое наследование в ООП» всегда есть готовый ответ на самом SO и я обычно не минусую, а закрываю вопрос как дубликат (после тысячи репутации в рубрике дается возможность помечать дубликатами ответы единолично.)
ilyaplot
22.07.2016 15:57+3Заходим на ru.stackoverflow.com/documentation/ — 404. Ок, наверное, позже можно ожидать. Заходим по ссылке, выбираем MySQL. Видим странный порядок материалов с заголовками View, INSERT, delete. Разве можно называть стандартом те системы, которые сами по себе не стандартизированы?
ilyaplot
25.07.2016 10:00Предложил правки, сегодня их приняли. Теперь VIEW, INSERT, DELETE. Уже лучше :)
Gitkan
22.07.2016 16:11+3Удивительно то, что на SO к написанию документации пригласили чуть ли не всех — даже тех, у кого репутации едва хватает на комментарии.
vedenin1980
23.07.2016 16:34+1Не удивительно, документацию должны заапрувить два человека даже если у тебя > 5 тыс. репутации (по крайне мере, у меня более 5 тыс. и все равно приходится ждать принятия).
ReinRaus
24.07.2016 16:06Когда новый сайт сети стэкэксчендж проходит бета-тестирование, то рамки репутации сильно занижены. С выходом из беты будет повышена репутация, необходимая для редактирования документации, и, скорее всего, нужно будет иметь знак по этой метке.
TimsTims
22.07.2016 16:11Хочется, конечно, чтобы была максимально полная энциклопедия по всем докам-мануалам. И да, чтобы она была максимально хорошо написана и структурирована. Но увы, будет что-то похожее на вики: информация как-бы есть, но часто на весьма базовом, справочном виде, и если тебе нужно копать дальше, то увы — никто этого еще не написал.
Это как в приколе из баша (текст примерный):
Учусь в универе на *физмате*. И если на 1-2 курсе информацию к экзаменам еще можно было надыбать в интернете, то уже на 4-5 курсах такой специфической информации в открытом доступе попросту нет и нам просто разрешают пользоваться мобильниками.
SamDark
22.07.2016 16:19Нормально выходит: http://stackoverflow.com/documentation/yii2
wispoz
22.07.2016 17:14То есть вы реально считаете что вот это:
stackoverflow.com/documentation/yii2/788/introduction-to-yii-2/2751/install-yii2-advanced-in-ubuntu#t=201607221330133801441
лучше чем здесь:
www.yiiframework.com/doc-2.0/guide-start-installation.html
?SamDark
22.07.2016 17:50Нет. Документацию мы вылизывали долго, а эта штука только запустилась.
wispoz
22.07.2016 17:51+1А смысл тратить силы на сторонний ресурс который еще и в Бете?
Может лучше новый сайт для Yii допилить?SamDark
22.07.2016 17:54+1Так никто особо сил и не тратит. Я там ради интереса пару статеек отредактировал за 10 минут и всё. Новый сайт может помочь допилить кто угодно: https://github.com/yiisoft-contrib/yiiframework.com
OlegMax
22.07.2016 16:50+6Очередное окончательное решение вопроса с документацией! Тысячи программистов, у которых всё не доходили руки дописать документацию по своим продуктам, облегченно вздохнули, теперь документацией с энтузиазмом займутся незнакомые индусы.
lexkazakov
22.07.2016 17:31А тут-то и загвоздка: нельзя так просто взять и добавить на SO доку по своей библиотечке/фреймворку/проекту.
1. Документация привязывается к существующему на SO тегу.
2. Если хочется добавить доку к своему проекту и у него есть тег, то надо открыть заявку (proposal).
3. За заявку (proposal) должны проголосовать не менее 5 человек. Голосовать могут только чуваки с положительно оценёными ответами по данному тегу или имеющие репутацию выше 150.ReinRaus
27.07.2016 22:54Это только кажется проблемой. На самом деле все решается за день-два.
Нужно создать вопрос на «Мета» с просьбой создать новую метку.
Объяснить, что Вы хотите создать ее для документирования своего фреймворка.
Очень быстро найдутся участники, которые проголосуют за создание метки.
Такие преценденты уже были. Человек с маленькой репутацией переносил с домашней страницы своей библиотеки мануал по ней в формате QA.
Все решаемо. На СО сидят люди, а не роботы.
private_tm
22.07.2016 22:47Вряд ли индусы будут там что то писать) Знания языка обычно как и программирования)
oduvan
23.07.2016 12:47+1У стековерфлоу давно существует проблема закостенелых решений. Очень часто встречается, когда гуглишь решения, касательно гита.
Решение, которое было актуальное и хорошее в 2013 — уже не так хорошо в 2016, но набрало уже 100500 апвотов.
С документацией будет тоже самое?vedenin1980
23.07.2016 16:39+1Запрос на изменения любого примера в документации может отправить любой, по сути, я так понимаю, будет вики-подобная модель, когда статьи правят всем миром.
Yahweh
23.07.2016 21:28+2Править тоже не выход, то что вышла новая версия продукта не значит что предыдущей(ими) перестали пользоваться и их надо «исправить».
vedenin1980
23.07.2016 23:53Исправить не обязательно переписать с нуля. Достаточно вставить дополнения в пост что в такой-то версии продукта команды такие, а с такой-то версии продукта — другие. В вике вполне с этим справляются.
OLDRihard
25.07.2016 11:34Я надеюсь SE не будет топить за то, что это именно платформа для документации.
То что я увидел в Яве и в еще паре тем больше похоже на гайды (ну если точнее даже на шпоры). Никакой воды, пример и описание. В случае если тебе нужно уточнить что-то конкретное (и ты знаешь, что ты ищешь), сервис идеален. Для меня, с моей дырявой памятью — уж точно.
И в тоже время он слишком краток и архаичен для изучения с 0ля. И я бы лучше оставил именно все так, переименовав сервис во что нибудь более подходящее.
alexkunin
Ссылка: http://stackoverflow.com/documentation