Про 200 webpack-плагінів для перформансу на конференції JavaScript fwdays'20 | 14 березня
×Закрыть

Есть ли стандарты написания тех.документации?

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

Ни у кого из девов нет опыта написания доков. Есть ли какие-то стандарты, для упрощения жизни всех? или у каждой компании свой вариант?

LinkedIn
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Есть ЕСКД, есть ИСО там всякие. Гуглится на раз.

Стандартов куча. Но пользы от них мало. Имхо самый лучший вариант это мануалы и туториалы. Те текст который несёт определенную цель — научить пользоваться той или иной штукой.

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

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

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

Например, есть у вас код алгоритма. Должно быть краткое описание простым языком основных вех алгоритма со ссылками на детальные его описания где-то в инете или статьи.
То же и по архитектуре. Описание простым языком с простыми картинками архитектуры большими мазками и описание интерфейсов модулей и потока данных.

ГОСТ из ранее обязательных. Из необязательных есть много в МЭК и ИСО.

Не совсем ясно о какой именно документации речь. Путь хотя бы код по стандартам языка документируют для начала.

Есть три вида документации:
0) Которая не соответствует ГОСТу, но её можно читать.
1) Которая писана по всевозможным стандартам, но читать её невозможно в силу подразумевания, что читая каждую строчку, ВСЁ ОСТАЛЬНОЕ ты уже знаешь наизусть.
2) То что писано техническими писателями, маркетологами, и прочими графоманами. Читать противопоказано, можете ненароком кого-нить убить. Желание точно возникнет. Челлендж — понять ЧТО ВООБЩЕ делает продукт, о котором написано пять томов бреда. Не как работает, не как пользоваться, а просто ЧТО ЭТО.

Так вот, документировано только то, что можно прочитать. Всё остальное — МЕГАТОННЫ МУСОРА, смешивающие с дерьмом всё, что пытались сделать программисты. Если у вас есть технический писатель, прикуйте его цепями к батарее.

Побуду кепом.
Для цього існують спеціально навчені люди — аналітики, чи, в гіршому випадку, технікал райтери. Ці люди, по ідеї, мають володіти техніками збору інформації та документації.

Если речь именно о технической документации готового продукта, не о требованиях и спецификациях, то должно быть как минимум 2 уровня:
— описание архитектуры (задача собственно для архитектора, тех. лида или самого синьористого синьора)
— документация кода
Документировать код комментариями и генерировать из них доки ваши девы должны уметь точно.

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

А то создают, понимаешь, мир за 6 дней, а потом и за тыщу лет не разгребёшь через какие интерфейсные щели Исаак родил Иакова

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

Юнит и интегрейщен тесты — лучшая документация.

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

Ага. Видел я проекты, где офигительно странный алгоритмы покрытые такими же странными юнит-тестами.
А документация — отсутсвует, и даже кто писал и что там — неизвестно.

А я видел проекты где было полно документации от которой толку ноль. Потому что есть писанина в верде, а есть код который там четт исполняет в рантайме.

Подписаться на комментарии