Ответы пользователя по тегу Документация
  • Какие инструменты для создания документации существуют?

    @kn0ckn0ck
    Продюсер
    Да их целая туча
    Ответ написан
    Комментировать
  • Как заставить readthedocs рендерить таблицы в markdown?

    @kn0ckn0ck
    Продюсер
    Да нет никаких проблем с таблицами, вот пруф.
    В приведенном фрагменте в последней строке не хватает 4-го столбца, возможно, это и сносит рендеринг.
    Ответ написан
    4 комментария
  • Системы для ведения технической документации?

    @kn0ckn0ck
    Продюсер
    Пробовал doxygen, но он по понятным причинам не умеет в авторизацию.

    А почему бы не запаролить доступ к документации средствами nginx или apache?
    Ответ написан
  • Какая программа подойдет мне для документации удаленных объектов?

    @kn0ckn0ck
    Продюсер
    GitHub.com
    Ответ написан
    Комментировать
  • Есть ли методологии/стандарты/лучшие практики описания требований разработчикам?

    @kn0ckn0ck
    Продюсер
    Да, их много разных. Отличаются в основном контекстом применения - где-то лучше работает одно, а где-то другое, например:

    1. просто - это User Story
    2. чуть сложнее - UseCases, IEEE 830-1998
    3. совсем тяжелый случай - ГОСТ 34, ГОСТ 19 или ГОСТ Р 51904-2002

    Для эксплуатационной документации посмотрите РД 50-34.698-90
    Ответ написан
    1 комментарий
  • Как сделать документацию к коду?

    @kn0ckn0ck
    Продюсер
    Есть две крайности, которых лучше избегать:
    1. красивая и исчерпывающая документация требует колоссальных ресурсов на поддержку
    2. сложно воспринимаемый код, без малейших подсказок с чего все начинается и чем заканчивается

    Стандартные решения:
    1. самодокументируемый код, составленный так, что читающий может понять что для чего и в какой последовательности работает.
    2. описание интерфейсов (назначение метода, тип/суть параметров и т.п.) в форме комментов в коде.
    3. автоматическая документация (генерится из комментариев) - эффективно, только если сам код закрыт.
    4. модульные тесты, фиксирующие требования к коду и демонстрирующие его использование.
    5. описание высокоуровневого дизайна (High Level Design, HLD), описывающий какие элементы существуют, их взаимосвязь друг с другом и основные сценарии взаимодействия.

    Работающая документация - это компромисс из этих практик, релевантный конкретной ситуации.

    Кстати, проектная работа, это не только документация к коду, это еще и свод правил, которые позволят архитектуре не расползтись кто в лес кто по дрова, а также сохранят стилистику написания кода для единообразия и легкой поддерживаемости кода.
    Ответ написан
    12 комментариев
  • Какие аналоги у ГОСТ 19.402-78?

    @kn0ckn0ck
    Продюсер
    Может быть это? ГОСТ 34.602-89 Информационная технология (ИТ). Комплекс стандартов на автоматизированные системы. Техническое задание на создание автоматизированной системы.
    Ответ написан
    Комментировать
  • Какие моменты отдела разработки, должны быть задокументированы?

    @kn0ckn0ck
    Продюсер
    Отделу разработки грех не стремиться к самодокументируемости. У вас так быстро растет отдел, что нет времени объяснить новчику в теч. пары часов как все устроено? Или у вас процесс разработки/деплоя вылит из гранита, что за устаревание/обновление докуметации вы не паритесь?

    1. Jenkins Pipeline (или Gitlab) - пример самодокументируемого деплоя
    2. аналогично п. 1
    3. Есть уже куча готовых, просто дать ссылку
    4. Показать и объяснить устно, чтобы снять сразу возможные вопросы/критику/непонятки
    5. Единственное что имеет смысл задокументировать (что редко меняется) - архитектурные особенности. Внутри каждого скрипта должны быть либо комментарии, либо код должен быть самодокументируем. Если нужно описать "клей", то почему бы не использовать Ansible/Chef для этих целей?
    6. "Никогда не нажимай эту красную кнопку..." - ну вы знаете, что затем последовало.
    Ответ написан
    Комментировать
  • Можно ли написать программу, не имея никакой документации и техзадания?

    @kn0ckn0ck
    Продюсер
    Спрашиваешь... так делают процентов 90. Другое дело - правильно ли они поступают при этом? Часто документацию путают с проектированием. Это разные вещи и у них разные цели.

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

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

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

    1. Зависит от сложности/объема задачи. Если все помещается в голове, то для чего тогда документация? Любая, UML или текст, не важно. Если что-то нужно продумать, то можно записать на доске/бумаге, сфоткать, потом выбросить.

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

    3. Уважительной причиной чего-то не делать будет четкое понимание того, как связанные с этим риски минимизируются. Долой догмы. Если в среднесрочной перспективе мы четко осознаем, что фиксация/документирование требований не принесет пользы, то зачем тратить на это время/ресурсы?
    Ответ написан
    Комментировать