Stackoverflow запустил раздел «Документация»

    Вчера произошло достаточно значимое событие на рынке разработки. Точнее в сфере поддержки и сопровождении программных продуктов. StackOverflow запустил раздел документация. Почему это важно?


    На протяжении последних лет, когда github захватил рынок дистрибуции исходных кодов, проблема документации стояла остро. Не смотря на удобство работы с кодом, github так и не смог предложить достойной системы ведения документации – wiki забрасываются, а вести их через cvs попросту слишком трудоемко. ReadTheDocs попробовавший решить эту проблему, явно не совершил переворота, подойдя к проблеме в лоб. Так же есть gitbook, но и его трудно назвать стандартом.


    На сегодня существуют следующие проблемы, с которыми сталкиваются разработчики:


    1. Отсутствие удобного способа вести многостраничную документацию со сложной навигацией.
    2. Необходимость взаимодействия множества авторов.
    3. Отсутствие единого стиля оформления документов. Возьмите туже документацию по Mongoose – раздражающие цвета, бедная подстветка синтаксиса.
    4. Необходимость выбора места хранения и дистрибуции.
    5. Проблемы "бумажной" работы сами по себе.

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


    1. Совместная разработка с поддержкой сравнений (diff).
    2. Запрос на создание статьи.
    3. Голосования за изменения, вместо единого автора.
    4. Стандартная система поощрения stackoverflow.

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

    Similar posts

    Ads
    AdBlock has stolen the banner, but banners are not teeth — they will be back

    More

    Comments 52

    • UFO just landed and posted this here
        –3
        Вы твитером ошиблись.
          +2
          Не уверен, что стандартный (ну немножко подпиленный) интерфейс SO идеально подходит для таких вики-доков, но в целом впечатление от нового раздела приятное и многообещающее. Взлетит. :)
          • UFO just landed and posted this here
              0
              Лучше бы сделали каталог по качественным ответам, а не писали их ещё раз.
            0
            По мне документация это иерархичное описание от простого к сложному, с наличием кросс ссылок, Diff к предыдущей версии. Для меня простым было бы писать в xml или WSWYG, но тот же конфлюенс — убог.
            Архитектурно для
            Идеально редактируешь у себя на компе, потом commit, и веб сервер уже подхватывает изменения и отображает. Для редактирования нужен редактор, который умеет отображать код как браузер. Все остальное, что пробовал — неудобно.
              0
              Так вроде ReadTheDocs подходит по описанию. Для Markdown разметки полно редакторов/плагинов. Требование обязательно XML как-то странно выглядит.
                0
                я имел ввиду xml-like
                  +8
                  Один пацан писал всё в xml,
                  и документацию, и DTO,
                  говорил что нравится, удобно, читабельно.
                  Потом его в дурку забрали, конечно.
                    0
                    То есть, просто косоглазием не отделался
                0
                По описанию сразу напрашивается GitHub Pages + любой удобный HTML/WYSWYG
                +1
                Теперь и на SO можно послать RTFMить
                  0
                  Да и раньше в гугол бодро посылали. Теперь идти недалеко)
                    0
                    В гугол посылать не много смысла, т.к. он на стековерфловочку и вернет.
                    Так что да, полезное (пока теоретически) нововведение. Особенно, если дока будет оперативно пополняться теми нюансами, о которых спрашивается.
                      0
                      Ну так вернет вопрошающего на уже существующий ответ) Направить в нужную сторону — уже половина дела.
                      +1
                      Я вот люблю специалистов, знающих о предмете понаслышке.

                      На SO всегда было специальным образом запрещено посылать в гугл и за такие ответы минусуют нещадно. Почитайте правила.
                        –1
                        Конечно минусуют, кто же додумается писать в ответ то, что им не является? В комментариях — ничего, вполне поддерживают, неоднократно инициировал закрытие вопросов с такой формулировкой.
                          0
                          Это странно, что удавалось с такой формулировкой инициировать закрытие. SO позиционируется как _база знаний_, посыл в гугл даже за самым тривиальным ответом противоречит логике ресурса. Я лично даже дубликаты закрываю очень осторожно.

                            0

                            Когда спрашивают элементарное из разряда "Что такое наследование в ООП" или что-то вида "вот задание домашней работы, напишите её за меня", то в гугл в комментариях посылают часто, более того минусуют тех кто отвечает на подобные вопросы.

                              0
                              Может быть, я лично никогда не видел минусов за ответы по таким соображениям. Но это очень сильно зависит от рубрики, конечно.

                              На вопросы типа «Что такое наследование в ООП» всегда есть готовый ответ на самом SO и я обычно не минусую, а закрываю вопрос как дубликат (после тысячи репутации в рубрике дается возможность помечать дубликатами ответы единолично.)

                    +3
                    Заходим на ru.stackoverflow.com/documentation/ — 404. Ок, наверное, позже можно ожидать. Заходим по ссылке, выбираем MySQL. Видим странный порядок материалов с заголовками View, INSERT, delete. Разве можно называть стандартом те системы, которые сами по себе не стандартизированы?
                      0
                      Предложил правки, сегодня их приняли. Теперь VIEW, INSERT, DELETE. Уже лучше :)
                      +3
                      Удивительно то, что на SO к написанию документации пригласили чуть ли не всех — даже тех, у кого репутации едва хватает на комментарии.
                        +1
                        А что, репутация на SO — это хороший показатель?
                          +6
                          Достаточный для отсеивания трэша.
                          +1

                          Не удивительно, документацию должны заапрувить два человека даже если у тебя > 5 тыс. репутации (по крайне мере, у меня более 5 тыс. и все равно приходится ждать принятия).

                            0

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

                            0
                            С нетерпением ждем выхода из Beta и появлении на русской версии stackoverflow!
                              +1
                              Русскую версию с нетерпением ждете, чтобы было еще больше проблем с актуальностью, противоречивостью описаний и тому подобной классики?
                                0
                                Нет, русскоязычными ресурсы кажутся более удобными и вызывают больше доверия.
                              0
                              Хочется, конечно, чтобы была максимально полная энциклопедия по всем докам-мануалам. И да, чтобы она была максимально хорошо написана и структурирована. Но увы, будет что-то похожее на вики: информация как-бы есть, но часто на весьма базовом, справочном виде, и если тебе нужно копать дальше, то увы — никто этого еще не написал.

                              Это как в приколе из баша (текст примерный):
                              Учусь в универе на *физмате*. И если на 1-2 курсе информацию к экзаменам еще можно было надыбать в интернете, то уже на 4-5 курсах такой специфической информации в открытом доступе попросту нет и нам просто разрешают пользоваться мобильниками.
                                0

                                Нормально выходит: http://stackoverflow.com/documentation/yii2

                                +6
                                Очередное окончательное решение вопроса с документацией! Тысячи программистов, у которых всё не доходили руки дописать документацию по своим продуктам, облегченно вздохнули, теперь документацией с энтузиазмом займутся незнакомые индусы.
                                  0
                                  А тут-то и загвоздка: нельзя так просто взять и добавить на SO доку по своей библиотечке/фреймворку/проекту.

                                  1. Документация привязывается к существующему на SO тегу.
                                  2. Если хочется добавить доку к своему проекту и у него есть тег, то надо открыть заявку (proposal).
                                  3. За заявку (proposal) должны проголосовать не менее 5 человек. Голосовать могут только чуваки с положительно оценёными ответами по данному тегу или имеющие репутацию выше 150.
                                    0
                                    Зачем на каком-то стороннем форуме писать доку к своему проекту?
                                      0
                                      OlegMax предлагает открыть заявку по своему проекту, чтоб другие люди писали документацию по нему на SO. А вы потом к себе скопируете.
                                      0

                                      Это только кажется проблемой. На самом деле все решается за день-два.
                                      Нужно создать вопрос на «Мета» с просьбой создать новую метку.
                                      Объяснить, что Вы хотите создать ее для документирования своего фреймворка.
                                      Очень быстро найдутся участники, которые проголосуют за создание метки.
                                      Такие преценденты уже были. Человек с маленькой репутацией переносил с домашней страницы своей библиотеки мануал по ней в формате QA.
                                      Все решаемо. На СО сидят люди, а не роботы.

                                        0
                                        Какую метку по какому проекту? Могу создать.
                                        0
                                        Вряд ли индусы будут там что то писать) Знания языка обычно как и программирования)
                                        +8
                                        Если кому-то интересно, есть еще ни на что не претендующий devdocs.io.
                                          –2
                                          Как же это замечательно!
                                            0
                                            Пока что больше похоже на cook book
                                              +1
                                              У стековерфлоу давно существует проблема закостенелых решений. Очень часто встречается, когда гуглишь решения, касательно гита.

                                              Решение, которое было актуальное и хорошее в 2013 — уже не так хорошо в 2016, но набрало уже 100500 апвотов.

                                              С документацией будет тоже самое?
                                                +1

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

                                                  +2

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

                                                    0

                                                    Исправить не обязательно переписать с нуля. Достаточно вставить дополнения в пост что в такой-то версии продукта команды такие, а с такой-то версии продукта — другие. В вике вполне с этим справляются.

                                                    0
                                                    Если будет «вики-подобная модель», то чем википедия плоха?
                                                  0
                                                  Я надеюсь SE не будет топить за то, что это именно платформа для документации.

                                                  То что я увидел в Яве и в еще паре тем больше похоже на гайды (ну если точнее даже на шпоры). Никакой воды, пример и описание. В случае если тебе нужно уточнить что-то конкретное (и ты знаешь, что ты ищешь), сервис идеален. Для меня, с моей дырявой памятью — уж точно.

                                                  И в тоже время он слишком краток и архаичен для изучения с 0ля. И я бы лучше оставил именно все так, переименовав сервис во что нибудь более подходящее.

                                                  Only users with full accounts can post comments. Log in, please.