Стандарт open source документации

[@smind]

как то немного странно что в тексте про open source документацию не упоминаются не man (nroff) ни doxygen…

[@Sannis]

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

Тем более, что не для всего что open source нужны man-страницы, и не для всех языков идеально подходит Doxygen :) Об этом я хочу отдельный пост написать.

[@darksith]

«я хотел бы предложить стандартый способ документирования проектов с открытым исходным кодом.»
А разве ГОСТ 24.207-80 не распространяется на такие проекты?

[@Sannis]

В России — в какой-то мере да. А за её пределами?

В предложенном варианте, кстати, несколько больше часто необходимых пунктов, чем в этом ГОСТе, который обновлялся в 86 году.

[@bear11]

Не все знают о существовании такого ГОСТ-а. И статья, и ГОСТ полезны.

[@Sannis]

Кстати, на хабре была статья по поводу ГОСТа: habrahabr.ru/post/122700

[@nazarpc]

Я целиком ЗА.
Документация, которая не дает понимания, как увидеть результат с минимальными усилиями за минимальное время оставляет плохое впечатление о продукте, и, скорее всего, пользователь к нему больше не вернется, ибо «когда-то пробовал — не получилось». Бывают конечно исключения, но в целом именно так.
Так что указанная концепция и общая идея мне нравится, вопрос только в том, как сделать, чтобы какая-то достаточно значительная часть разработчиков Open Source начала этому следовать.

[@Sannis]

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

[@AlexAkimov]

Мне немного странно другое: что в этом тексте совсем не упоминаются технические писатели :-) Ведь это именно их работа — создавать документацию, и у них уже есть свои наработки и стандарты в этой области. Хотя, безусловно, в области open source наверное трудно найти ещё и open source техрайтера…

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

[@vorobyev]

Стандарты для технических писателей обычно содержатся в ГОСТах или внутрикорпоративных гидах по стилям. Обычно они специально разрабатываются для определенного класса систем на основе реального опыта использования.

Создание же универсального шаблона может оказаться затруднительным, блоки критически важные для одних приложений( в рамках статьи это может быть, например, API для web-приложений) могут оказаться совсем ненужными в других( в игре API может вообще не содержаться, зато будет критически важно красочное описание GUI).

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

[@Sannis]

Да, тут речь именно про open source проекты. Они, порой, не очень крупные и не требуют даже той документации, которая излагается в нашем ГОСТе. Но часто авторы даже не знают, как лучше писать README. Что уж и говорить, я сам к этому долго шёл, потому и посчитал что перевод будет полезен.

Спасибо ;)

[@vorobyev]

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

При этом проблема плохой документированности скорее социальная, нежели техническая. Создание документа может оказаться задачей сравнимой по трудозатратам с написанием кода и требующей сравнимой квалификации исполнителя. При этом она не добавит функциональности продукту. Поэтому мотивация на написание документации у разработчика низка( людям интереснее самовыражаться через развитие возможностей ПО, чем через написание технических текстов). А потом автор обычно и сам знает как работает программа: часто изначально программа пишется «для себя», при этом мотивация написать есть, а документировать уже не важно( кому надо — сам разберется).

К другим идеям из этой статьи. Включение документации в репозиторий с кодом — очень спорное решение. И этому есть 2 причины:
а. изменение документации будет влиять на версию продукта.
б. часто документация включает в себя значительный объём бинарных данных( изображения например), включение их в репозиторий может привести к значительному увеличению объёма хранимых данных.
Предложенный автором Wiki способ хранить документацию кажется более реальным.

[@Sannis]

Обычно документацию кладут в отдельный репозиторий. Тем более, что на github.com, например, можно использовать встроенную wiki, которая построена над git-репозиторием. Это удобно и для пользователей и для матёрых программистов. Автор как раз пишет о том, что часто необходимо разделять документацию, так что README и справку по API можно обновлять в основном репозитории при выпуске новой версии, а руководство построить на базе wiki.

[@vorobyev]

Здесь скорее вмешивается ваш опыт. Действительно документацию разумно хранить в отдельном репозитории. Автор пишет нам, что:

Именно поэтому я настоятельно рекомендую, чтобы разделы I, II и III были включены в репозиторий исходного кода проекта, где они могут быть проверены и отредактированы кем угодно.

И именно проблемам с хранением раздела III в репозитории проекта и был посвящен мой комментарий.

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

[@Sannis]

Да, с этим я согласен. Хранить часть III в основном репозитории может быть накладно. Но в начале можно и так, а когда наберётся большое количество статей — выделить в отдельный репозиторий. Наличие в части III большого количества графики или иных ресурсов тоже зависит от проекта. Взять к примеру документацию к компонентам LAMP — там картинки только в виде графиков попадаются.