Есть ли стандарты написания тех.документации?
Назрел вопрос, в маленькой продуктовой компании нет документации. Вроде годами пилят продукт, но для избежания в будущем недопонимания, как и что работает, оунеры решили, что пришло время задокументрировать.
Ни у кого из девов нет опыта написания доков. Есть ли какие-то стандарты, для упрощения жизни всех? или у каждой компании свой вариант?
17 коментарів
Додати коментар Підписатись на коментаріВідписатись від коментарівЕсть ЕСКД, есть ИСО там всякие. Гуглится на раз.
Стандартов куча. Но пользы от них мало. Имхо самый лучший вариант это мануалы и туториалы. Те текст который несёт определенную цель — научить пользоваться той или иной штукой.
Стандарты есть, можно нагуглить. Но ценность имеет согласованный формат понятный и принятый всеми участниками процесса разработки. Ну и в общем виде, есть несколько уровней описаний, вроде такого:
— соглашение об именовании и стандартах написания кода, библиотека имен, описание структур данных, описание архитектуры (деление на составные элементы и их взаимосвязи);
— тесты
— требования и тех задания в формате «как хотим» и описание итога «как есть» (тут собственно бизнес логика, бизнес артефакты и прочее «аналитическое» и «проектировочное»)
— пользовательская документация и кейсы для саппорта (первая, вторая линия)
Самое главное, эти документы должны быть «живыми» и затраты на поддержания их жизни — приемлемыми, иначе оно умрет. Оптимально, иметь выделенного толкового человека, который будет анализировать состояние документации и процесса документирования и донимать до печенок его участников, что бы те вовремя выполняли свои маленькие шаги по ее формированию. Потому что выполнить документирование одним махом... это «глыба», почти как переписать его с нуля (рефактоинг удобное время для запуска процесса документирования).
Не совсем ясно о какой именно документации речь. Путь хотя бы код по стандартам языка документируют для начала.
Есть три вида документации:
0) Которая не соответствует ГОСТу, но её можно читать.
1) Которая писана по всевозможным стандартам, но читать её невозможно в силу подразумевания, что читая каждую строчку, ВСЁ ОСТАЛЬНОЕ ты уже знаешь наизусть.
2) То что писано техническими писателями, маркетологами, и прочими графоманами. Читать противопоказано, можете ненароком кого-нить убить. Желание точно возникнет. Челлендж — понять ЧТО ВООБЩЕ делает продукт, о котором написано пять томов бреда. Не как работает, не как пользоваться, а просто ЧТО ЭТО.
Так вот, документировано только то, что можно прочитать. Всё остальное — МЕГАТОННЫ МУСОРА, смешивающие с дерьмом всё, что пытались сделать программисты. Если у вас есть технический писатель, прикуйте его цепями к батарее.
www.tcworld.info/...r-software-documentation
Побуду кепом.
Для цього існують спеціально навчені люди — аналітики, чи, в гіршому випадку, технікал райтери. Ці люди, по ідеї, мають володіти техніками збору інформації та документації.
Додай їх до списку
Если речь именно о технической документации готового продукта, не о требованиях и спецификациях, то должно быть как минимум 2 уровня:
— описание архитектуры (задача собственно для архитектора, тех. лида или самого синьористого синьора)
— документация кода
Документировать код комментариями и генерировать из них доки ваши девы должны уметь точно.
В правильной компании сначала должен быть документ, а потом продукт разрабатывается.
А то создают, понимаешь, мир за 6 дней, а потом и за тыщу лет не разгребёшь через какие интерфейсные щели Исаак родил Иакова
Я не понимаю. Может я не очень умный, но я даже для себя сначала по возможности прописываю основные моменты и структуры.
Юнит и интегрейщен тесты — лучшая документация.
Тесты которые покрывают бизнес логику уже будет супер, а марать доки в клауде с описанием вашего кода это бесполезная работа, ну кроме как случая когда у вас нереально сложные структуры данных и алгоритмы которые сложно понять без графиков и описания как они работают.
Ага. Видел я проекты, где офигительно странный алгоритмы покрытые такими же странными юнит-тестами.
А документация — отсутсвует, и даже кто писал и что там — неизвестно.
А я видел проекты где было полно документации от которой толку ноль. Потому что есть писанина в верде, а есть код который там четт исполняет в рантайме.