Комментарии 20
Корректорское замечание. После изображений «Среднестатистическая автомастерская — Среднестатистический автомеханик» помещены два одинаковых куска текста (различаются только знаками препинания в последнем предложении).
Актуально. Исходя из своего опыта склонен считать, что разработка без документации или, что еще хуже, без задачи в трекере, должна быть отнесена к техническому долгу. С большой вероятностью это будет недостаточно продуманное решение, которое в потоке работы забудется. Когда настанет момент поддержки (как известно, в любом коде есть как минимум одна ошибка) придется долго и лихорадочно заниматься "археологией по коду".
На своих проектах я пытаюсь сделать так, чтобы задача в трекере одновременно выполняла и функции документирования.
Шаблон описания задачи
Получается с переменным успехом, но, в целом, подход себя оправдывает.
Для чего-то бо́льшего лучше сразу набросать и зафиксировать архитектуру.
Пример фрагмента архитектуры
При наличии таких схем, к примеру, процесс "онбоардинга" существенно упрощается.
Если хотя бы в трекере оставить следы с описанием, что вообще было реализовано, то это уже хорошо. Я придерживаюсь позиции, что документация на систему должна храниться в предназначенном для этого месте — Confluencem Notion и т.п., а не в таск-трекере.
Шаблон описания задачи — отличная практика! У нас в компании он тоже внедрен. Его его целевое назначение не сохранение документации, а точка входа в статью с документацией.
Основное из шаблона:
Шаблон описания задачи — отличная практика! У нас в компании он тоже внедрен. Его его целевое назначение не сохранение документации, а точка входа в статью с документацией.
Основное из шаблона:
- бизнес-требования,
- постановка задачи (кратко) со ссылкой на подробное описание реализации,
- описание миграций данных,
- рекомендации к тестированию,
- о мониторинге и т.п.
Я придерживаюсь позиции, что документация на систему должна храниться в предназначенном для этого месте — Confluencem Notion и т.п., а не в таск-трекере
А в чем преимущество такого подхода? Вот фрагмент "самодокументации" из одного моего проекта:
Каждая ссылка ведет на задачу, задачи оформлены по шаблону. Если нужно что-то вспомнить — заходишь в оглавление, открываешь задачу и читаешь. Для внутренней документации — самое то.
На мой взгляд, это самый омерзительный случай — страдают все: и те, кто пишет документацию – нудно, скучно, бессмысленно потраченные силы на соблюдение каких-нибудь ГОСТов, и те, кто потребляет ее – обязанность заказать и оплатить документацию по ГОСТу, потому что так надо.
Если делать по ГОСТ "для галочки", то это, конечно, так себе удовольствие.
Но вот если "с душой" :), с чувством, с толком, с расстановкой, то вполне полезные вещи можно обнаружить. Взять, к примеру, милейший документ ГОСТ 19.404-79 ПОЯСНИТЕЛЬНАЯ ЗАПИСКА.
1.2. Пояснительная записка должна содержать следующие разделы:
- введение;
- назначение и область применения;
- технические характеристики;
- ожидаемые технико-экономические показатели;
- источники, использованные при разработке.
Чем плохо? Можно, конечно, сказать, что "ожидаемые технико-экономические показатели" это "фу", особенно "экономические...". Да все понятно, микросервисы наголо и помчались. Но разве не полезно понимать — а что же бизнес получит от этого всего?
Ну и далее:
2.3. Раздел «Технические характеристики» должен содержать следующие подразделы:
- постановка задачи на разработку программы, описание применяемых математических >методов и, при необходимости, описание допущений и ограничений, связанных с выбранным математическим материалом;
- описание алгоритма и (или) функционирования программы с обоснованием выбора схемы алгоритма решения задачи, возможные взаимодействия программы с другими программами;
- описание и обоснование выбора метода организации входных и выходных данных;
- описание и обоснование выбора состава технических и программных средств на основании проведенных расчетов и (или) анализов, распределение носителей данных, которые использует программа.
Если это все заполнено кратко и по делу, то такая документация будет очень полезной.
Далеко не все понимают, что документация — это тоже система, которая должна строиться по определенным принципам и отвечать требованиям большинства своих пользователей. Обычно документацией зовется нечто скомканое, описывающее текущий или уже давно прошедший момент во времени. Грамотно выстроенная практика документирования либо есть с самого начала разработки системы, либо её нет совсем. Практически нереально с нуля на более-менее сложных системах начать их документирование уже в процессе эксплуатации, потому и создаются временные стрезы, актуальные на момент начала их формирования, но сама документируемая система уже уехала в своем развитии дальше.
Если начать документирование «на горячую», то всегда будет неописанный хвост — тех. долг по документированию. Он либо будет закрыт, либо нет.
Если подойти к процессу документирования как к части процесса разработки, то обновление документации можно сделать нормой. Например, внедрив практику оформления отдельного сабтаска «Документирование» к задачам на разработку
Если подойти к процессу документирования как к части процесса разработки, то обновление документации можно сделать нормой. Например, внедрив практику оформления отдельного сабтаска «Документирование» к задачам на разработку
Далеко не все понимают, что документация — это тоже система, которая должна строиться по определенным принципам и отвечать требованиям большинства своих пользователей.
Этому, как бы, должны учить. Как в проектировании бетонно-железных артефактов учат(?). Но в нашей индустрии привычки какие-то другие. Документация — а как получится, кто-нибудь как-нибудь напишет.
Спасибо автору за смелость: утверждать, что необходимо документировать разработку системы, сейчас непопулярно и даже очень непопулярно! Согласен с автором во всем! Кроме одного. На протяжении всей статьи автор оправдывается за это свое мнение. Видать очень велик страх нарваться на осуждение в комментариях. Поэтому Ваш вывод
Причины отсутствия документирования две:
1) лень. И это простительно, т.к. в природе человека. На этот случай есть погоняло — руководитель проекта и грамотный заказчик;
2) безграмотность, невежество разработчиков. Это уже непростительно. Лечится только рублем. Иногда даже через хозяйственный (арбитражный) суд.
Выбирайте, если есть желание.
Даже в самой простой доработке есть две стороны с противоположными интересами: заказчик и разработчик, даже, если они работают на одном предприятии. Любой проектный документ — это договор между ними. Если обе стороны добросовестны, то он может и не понадобится. А если результат неудовлетворительный?
Поверьте старому разработчику — в программировании есть две самые большие проблемы:
1. Добиться от заказчика вменяемого изложения требований.
2. Доказать заказчику, что программа сделана в строгом соответствии с его требованиями.
Проектируйте, господа, проектируйте! И будет вам счастье.
Успехов!
Процесс документирования нужен далеко не всегда и это нормально.это ошибка! Приведите пример и дайте разумное обоснование, когда документирование не нужно! Примеры отсутствия документирования и вообще проектирования есть, и, чем далее, тем более. Но разумного в этом ничего нет! И быть не может!
Причины отсутствия документирования две:
1) лень. И это простительно, т.к. в природе человека. На этот случай есть погоняло — руководитель проекта и грамотный заказчик;
2) безграмотность, невежество разработчиков. Это уже непростительно. Лечится только рублем. Иногда даже через хозяйственный (арбитражный) суд.
Выбирайте, если есть желание.
Даже в самой простой доработке есть две стороны с противоположными интересами: заказчик и разработчик, даже, если они работают на одном предприятии. Любой проектный документ — это договор между ними. Если обе стороны добросовестны, то он может и не понадобится. А если результат неудовлетворительный?
Поверьте старому разработчику — в программировании есть две самые большие проблемы:
1. Добиться от заказчика вменяемого изложения требований.
2. Доказать заказчику, что программа сделана в строгом соответствии с его требованиями.
Проектируйте, господа, проектируйте! И будет вам счастье.
Успехов!
Приведите пример и дайте разумное обоснование, когда документирование не нужно!
Если продукт свой, заказчика нет и нужно запустить быстро, без выделения времени на описание, то, например, встроенные комментарии в код спасают. Это нельзя назвать проектной документацией, потому что к ней не все имеют доступ, а только разработчики.
На протяжении всей статьи автор оправдывается за это свое мнение.
Главная мысль статьи — смотреть на масштаб проекта. Не всегда экономически целесообразно сразу выделять ресурс на документирование и заказчика не убедить.
Даже в самой простой доработке есть две стороны с противоположными интересами: заказчик и разработчик
Рассмотрим документирование требований — договор между заказчиком и разработчиком. Требования, конечно, тоже документация, но не всегда в том объеме, чтобы помочь разобраться — как работает система. К тому же, в ходе разработки, требования имеют свойство меняться и уточняться, не всегда эти изменения и уточнения фиксируются в том самом оригинале договора и знания теряются. Такая вот грустная практика до сих пор существует.
Если продукт свой, заказчика нет и нужно запустить быстро, без выделения времени на описание, то, например, встроенные комментарии в код спасают.Заказчик есть всегда! Это не только функция, но и роль, которую может играть даже член команды проекта. Я уверен, что «заказчики» есть и Вашей команде, только Вы их таковыми не считаете. И зря. Можно специально назначать такого «заказчика» и увидите, что он значительно поднимет вам качество работы.
А комментарии в коде — это элемент стиля программирования, это отношение программиста к своему коллеге, которые возможно будет разгребать написанное. Относитесь к нему уважительно, и Вам будет приятно работать, да и, как знать, может через годик-другой самим придется разгребать свое творчество.
Главная мысль статьи — смотреть на масштаб проекта. Не всегда экономически целесообразно сразу выделять ресурс на документирование и заказчика не убедить.Документирование — это не вопрос экономической целесообразности. Это вопрос качества работы команды проекта, и в этом вопросе надо не заказчика убеждать, а себя, если это еще не стало у вас нормой.
А качество, естественно, косвенно, но влияет и на экономику проекта, и очень даже часто, сильно влияет. И качество работы уж совсем не зависит от масштаба проекта. Как известно ложка дегтя может испортить бочку меда! Хотите долго задержаться на рынке — повышайте качество работы и даже на мелких проектах. Более того, беритесь за проекты, которые завалили ваши конкуренты. Это самая интересная и благодарная работа.
Требования, конечно, тоже документация, но не всегда в том объеме, чтобы помочь разобраться — как работает система. К тому же, в ходе разработки, требования имеют свойство меняться и уточняться...Согласен. Часто заказчик сам не понимает чего хочет, но еще чаще, он не понимает возможностей автоматизации. Поэтому относитесь к требованиям заказчика, как к своим. Для этого есть прекрасный механизм, например, обследование бизнес-процессов заказчика. По результатам обследования вместе проведете оптимизацию и напишете новые требования и ТЗ. Тогда они уже не будут меняться и уточняться. А если и будут, то только совершенствоваться.
Такая вот грустная практика до сих пор существует.Все в ваших руках и мозгах! Поверьте, проектирование — это не только интересно, но и весело! Особенно на незнакомом объекте. Нет ничего более интересного, чем процесс познания нового.
Но хорошее ТЗ, написанное совместно с заказчиком, это не только чувство удовлетворения от хорошо сделанной работы, но это и еще эффективное средство повышения производительности труда программиста — это его шпаргалка, или даже настольная книга до самого окончания проекта. Если будете писать такие ТЗ, то всей команде будет весело. И заказчик легче будет подписывать счета на оплату.
Проектируйте, господа, проектируйте!
Заказчик есть всегда!
Все так. В нашей компании есть роль заказчика, и он не один. Это владельцы продуктов — подсистем МоегоСклада.
Это вопрос качества работы команды проекта
В точку! Это можно добавить как один из положительных результатов по итогам внедрения документирования: требований, результатов проектирования и реализации.
требования и ТЗ. Тогда они уже не будут меняться и уточняться. А если и будут, то только совершенствоваться.
Тут еще можно добавить про уровни детализации. На этапе ТЗ с заказчиком, важно сделать проработку того, что видит пользователь, какие есть бизнес-правила и ограничения, и так далее. Все это — бизнес-требования. Они идут в основу ТЗ и это обычно то самое, что Заказчик осознанно читает и подписывает.
Но на бизнес-требованиях документирование не должно кончаться. Нужно проработать архитектурное решение, его гибкость, масштабируемость, описать его. Проработать поведение системы. Много деталей, которые влияют на результат.
Убедить заказчика в том, что проектирование и документирование нужны — не сложно. Достаточно хотя бы задать вопрос: «Вы же потом планируете развиваться?». Но по неизвестным причинам я часто слышу: «У нас нет документации», «У нас нет времени на это». Почему за обеспечение качества не хотят браться? Подозрение, что экономят (конечно, ошибочно думают, что экономят!).
Зачем жертвовать качеством, строить странные процессы разработки, жить без группы тестирования и т.д., если это приводит к печальным последствиям — огромнейшая тема для обсуждения! Ей нужно посвящать отдельную статью. Но такое сегодня все еще есть!
Я безмерно восхищаюсь, что в нашем продукте обеспечивают качество, следят за этим и стремятся к постоянному совершенствованию процесса разработки.
Но есть рынок труда. Есть другие компании и их сотрудники, с которыми общаешься на конференциях, собеседованиях, в тематических чатах, и видишь, что в их компаниях такой задачи как «документирование» нет, но им этого явно не хватает. Людям не хватает уверенности и аргументов для убеждения своего заказчика, что надо строить процессы правильно!
До последней строки поддерживаю Ваш комментарий. Надеюсь, что много читателей доберутся до него и извлекут для себя убедительных аргументов: «Документация нужна»!
Было бы уместно упомянуть MIL-STD-498, в котором работают разработчики промышленного софта (западные). Вот уж точно ничего не забудешь
Произвольный кусок из System Design Description
c. Characteristics of individual data elements that the interfacing entity(ies) will provide, store,
send, access, receive, etc., such as:
1) Names/identifiers
Project-unique identifier
Non-technical (natural-language) name
DoD standard data element name
Technical name (e.g., variable or field name in code or database)
Abbreviation or synonymous names
Data type (alphanumeric, integer, etc.)
Size and format (such as length and punctuation of a character string)
Units of measurement (such as meters, dollars, nanoseconds)
Range or enumeration of possible values (such as 0-99)
Accuracy (how correct) and precision (number of significant digits)
Priority, timing, frequency, volume, sequencing, and other constraints, such as whether
the data element may be updated and whether business rules apply
8) Security and privacy constraints
9) Sources (setting/sending entities) and recipients (using/receiving entities)
d. Characteristics of data element assemblies (records, messages, files, arrays, displays,
reports, etc.) that the interfacing entity(ies) will provide, store, send, access, receive, etc.,
such as:
1) Names/identifiers
Project-unique identifier
Non-technical (natural language) name
Technical name (e.g., record or data structure name in code or database)
Abbreviations or synonymous namesSoftware Design Description (SDD)
(PDF version)
DI-IPSC-81435
2) Data elements in the assembly and their structure (number, order, grouping)
3) Medium (such as disk) and structure of data elements/assemblies on the medium
4) Visual and auditory characteristics of displays and other outputs (such as colors,
layouts, fonts, icons and other display elements, beeps, lights)
5) Relationships among assemblies, such as sorting/access characteristics
6) Priority, timing, frequency, volume, sequencing, and other constraints, such as whether
the assembly may be updated and whether business rules apply
7) Security and privacy constraints
8) Sources (setting/sending entities) and recipients (using/receiving entities)
e. Characteristics of communication methods that the interfacing entity(ies) will use for the
interface, such as:
f.
Project-unique identifier(s)
Communication links/bands/frequencies/media and their characteristics
Message formatting
Flow control (such as sequence numbering and buffer allocation)
Data transfer rate, whether periodic/aperiodic, and interval between transfers
Routing, addressing, and naming conventions
Transmission services, including priority and grade
Safety/security/privacy considerations, such as encryption, user authentication,
compartmentalization, and auditing
Characteristics of protocols the interfacing entity(ies) will use for the interface, such as:
Project-unique identifier(s)
Priority/layer of the protocol
Packeting, including fragmentation and reassembly, routing, and addressing
Legality checks, error control, and recovery procedures
Synchronization, including connection establishment, maintenance, termination
Status, identification, and any other reporting features
send, access, receive, etc., such as:
1) Names/identifiers
Project-unique identifier
Non-technical (natural-language) name
DoD standard data element name
Technical name (e.g., variable or field name in code or database)
Abbreviation or synonymous names
Data type (alphanumeric, integer, etc.)
Size and format (such as length and punctuation of a character string)
Units of measurement (such as meters, dollars, nanoseconds)
Range or enumeration of possible values (such as 0-99)
Accuracy (how correct) and precision (number of significant digits)
Priority, timing, frequency, volume, sequencing, and other constraints, such as whether
the data element may be updated and whether business rules apply
8) Security and privacy constraints
9) Sources (setting/sending entities) and recipients (using/receiving entities)
d. Characteristics of data element assemblies (records, messages, files, arrays, displays,
reports, etc.) that the interfacing entity(ies) will provide, store, send, access, receive, etc.,
such as:
1) Names/identifiers
Project-unique identifier
Non-technical (natural language) name
Technical name (e.g., record or data structure name in code or database)
Abbreviations or synonymous namesSoftware Design Description (SDD)
(PDF version)
DI-IPSC-81435
2) Data elements in the assembly and their structure (number, order, grouping)
3) Medium (such as disk) and structure of data elements/assemblies on the medium
4) Visual and auditory characteristics of displays and other outputs (such as colors,
layouts, fonts, icons and other display elements, beeps, lights)
5) Relationships among assemblies, such as sorting/access characteristics
6) Priority, timing, frequency, volume, sequencing, and other constraints, such as whether
the assembly may be updated and whether business rules apply
7) Security and privacy constraints
8) Sources (setting/sending entities) and recipients (using/receiving entities)
e. Characteristics of communication methods that the interfacing entity(ies) will use for the
interface, such as:
f.
Project-unique identifier(s)
Communication links/bands/frequencies/media and their characteristics
Message formatting
Flow control (such as sequence numbering and buffer allocation)
Data transfer rate, whether periodic/aperiodic, and interval between transfers
Routing, addressing, and naming conventions
Transmission services, including priority and grade
Safety/security/privacy considerations, such as encryption, user authentication,
compartmentalization, and auditing
Characteristics of protocols the interfacing entity(ies) will use for the interface, such as:
Project-unique identifier(s)
Priority/layer of the protocol
Packeting, including fragmentation and reassembly, routing, and addressing
Legality checks, error control, and recovery procedures
Synchronization, including connection establishment, maintenance, termination
Status, identification, and any other reporting features
Из собственного опыта. Как бэкенд-разработчик на проекте веду:
- Покрытие кода комментариями JavaDoc для коллег-бэкендеров.
- Текстовое описание бизнес-логики в Confluence, для всех разработчиков на проекте.
- И swagger на dev-сервере, чтобы пощупать методы и описать их request-response.
Да, это усилия, но таковы правила компании. Не могу сказать, что меня это напрягает.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Момент, когда проектная документация нужна