Документация больших и 'пёстрых' софтовых проектов

Вроде тут были технические писатели в том числе.

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

Поделитесь опытом, что на эту тему есть почитать и с самого начала предусмотреть внедрение.

Я не знаю, глоссарии, трансклюзия, шаблоны, всё что угодно.

Тема — сопровождение софта, упор на типовые инструкции, наверное.

Уточнение: основная проблема не в стиле и не в стандартах. Основная проблема в том, что документацию должно быть удобно поддерживать сотрудникам из разных команд.

1 симпатия

Я бы попробовал что-то рассказать, но больше собирал методологии :slight_smile:

Описывал бизнес процессы и потом менял документацию по мере необходимости. Такая была у меня инструкция пользования АЗС, листов на 200-300

Три очевидных варианта:

  1. По стандарту той конторы, куда будете представлять.
  2. По ГОСТ.
  3. По нормам GitHub.
1 симпатия

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

Правильно понимаю?

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

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

Но справедливости ради, грамотная и структурная документация сильно упрощает жизнь.

1 симпатия

Прогресс бы вымыл. Но он давно закончился.

1 симпатия

Кое-какую идею я нащупал и сейчас с ней играюсь. Идея почёрпнута в общих чертах из чатика и форума, и вот в чём она заключается.

1: В основном люди пишут документацию в виде огромных портянок, которые страшно лишний раз трогать
2: То, что очевидно для одного человека, может оказаться неочевидным для другого.
3: Разные люди отвечают за разные аспекты поддержки приложения

Берём идею атомарных заметок, трансклюзию, шаблоны, немного иерархии и немного тегов.

Иерархия выглядит, допустим, следующим образом:

  • Служебная директория
    • Глоссарий
    • Выкладка
    • Мониторинг
  • Документация разработчиков
  • Документация сопровождения

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

Когда нужно составить документ для разработчиков или администраторов, мы набираем из служебной директории “кубики”. На “кубики” вешаются тэги.

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

“Человеческие” документы состоят из объяснений, как стыкуются между собой части и почему так сделано.

Может получиться интересно.

Попытка применить Zettelkastel-подобную схему в программировании называлась Literate Programming - разбиение программы при написании на маленькие фрагменты с указанием ссылок и документированием. Потом две отдельные программы делали из этой заготовки программу и полную документацию (с оглавлениями и глоссарием). К сожалению, это, как раз и привело к появлению

В обычных производственных системах документирования такого не бывает, наоборот, старая портянка копируется почти без изменений. Вплоть до:
1-ое изделие: Надо разобраться: полгода тебе на анализ, три месяца - на отчет.
2-ое изделие: Ну анализ почти такой же, как и в первый раз, новый только отчет, три месяца на все.
3-е изделие: Знаешь, изделие-то еще и не начинали делать, но пока отчет напишешь, месяца за три, может, сделают?

Это не принцип zettelkasten, это обычная декомпозиция.

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

Описывается каждый кусок отдельно. Куски по необходимости собираются инклюдами в документы: свой набор для QA, свой для админов и т.д.

Теги и ссылки по вкусу.

Я щас сделал прототип в Confluence, мне нравится. Но вообще оно независимо от вики, могу аналогично в Org-mode накидать.

Главное не упороться.

1 симпатия

Задача была несколько сложнее, но мне кажется я подход нащупал.

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

Мне крайне интересно посмотреть что получиться. Хотя бы на кусочек.

В свое время работая в газпромнефти мы придумали КФК, книгу функционального качества.

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

Если я эту фигню продам, постараюсь что-нибудь где-нибудь развернуть для демонстрации.

Да даже если и нет.

1 симпатия
  1. Атомарные блоки документации лучше писать в простом формате: markdown, asciidoc, rst.
  2. Готовые руководства лучше собирать отдельно под каждую целевую аудиторию (пользователи, админы, поддержка, разработчики, …).
  3. Формат готовых руководств - online html с хорошим поиском + загружаемый pdf. В виде ваулта мало кто оценит, наверно :grin:
  4. Как именно структурировать информацию, подсмотрите в документации по похожим продуктам Яндекс, Google.
  5. Глоссарий и стилистическое руководство с определенного уровня зрелости документации должны быть.
2 симпатии

1 и 2 - шо я и подумал

По остальным пунктам есть нюанасы.

1 симпатия