Как стать автором
Обновить

Техническая документация в разработке ПО: кто, зачем, когда и как описывает проект

Время на прочтение 6 мин
Количество просмотров 72K
Всего голосов 12: ↑11 и ↓1 +10
Комментарии 22

Комментарии 22

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

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

А пример?

К сожалению, пример показать не можем, так как у нас существует соглашение о неразглашении, но в качестве примера можно привести один из самых часто составляемых документов — ФТ. Что это такое и как его составлять, можно почитать тут:
habr.com/ru/company/retailrocket/blog/431572
Было интересно. И полезно. Спасибо.
Поправили, спасибо.

Ещё пробелы уберите перед знаками препинания, а то сразу видно, что один человек в диалог играл.

Технические писатели, значит, есть. Интересно, а будут когда-нибудь технические поэты?
НЛО прилетело и опубликовало эту надпись здесь
НЛО прилетело и опубликовало эту надпись здесь
В этом состоит одна из задач технического писателя, чтобы разузнать все составляющие системы и логику взаимодействия между ними у тех членов команды, которые обладают этими знаниями и задокументировать это.
НЛО прилетело и опубликовало эту надпись здесь
Добрый день, Даша, именуемая себя «техническим писателем». Ваша статья очень слабовата без (далее как пример):
1) перечня компетенций, которые необходимы «техническому писателю» для описания
информационная безопасность клиентов и самого банка, соответствие законам
даже если ему это будут надиктовывать специалист ИБ и специалист юридического отдела.
2) Указания причин по которым профильные специалисты не могут в рамках своих компетенций заполнить соответствующие разделы проектно-эксплуатационной документации.
В нашей компании технический писатель должен обладать такими компетенциями как: умение собирать информацию необходимую для работы, умение писать документы отвечающие требованиям ГОСТ серии 19 и 34, умение работать в команде, а также обладать знаниями процесса и методологий разработки программного обеспечения, его тестирования, описания бизнес-процессов и функциональных требований, структуры данных, дизайна экранных форм.

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

Профильные специалисты вполне могут в рамках своих компетенций заполнить соответствующие разделы проектно-эксплуатационной документации. И возможно смогут собрать все разделы в один документ. Но у нас в компании за это отвечает технический писатель.
Дарья, тогда разрешите задать следующие вопросы:
документы отвечающие требованиям ГОСТ серии 19 и 34

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

Судя по описанию требований к вакансии «технический писатель» у вас данный специалист имеет зарплату не менее в 2 раза большую, чем тестировщики, бизнес-аналитики, UX-дизайнеры?

Как относятся профильные специалисты к тому, что «специально-обученный» человек периодически требует от них информацию, которую почти дословно переносит в результирующий документ? — Поясню этот вопрос: в текущих реалиях при возможностях совместного редактирования документов и наличия различных инструментов автоматизации подготовки документации — требуются минимальные усилия профильного специалиста для заполнения «своего» раздела — при том, что исключается возможность не корректной интерпретации информации передающийся в документ третьим лицом. А то, разработчики и прочие творческие люди у нас народ спорить не любящий, он сказал одно, «техпис» написал как понял — исказив смысл, а разработчик спорить не стал — зачем время терять — все не он отвечает за достоверность документа.
В случае с наличием технического писателя — кто отвечает за достоверность информации отображенной в документе?

Перечитав несколько комментариев, пожалуй, отвечу здесь. Господа, под техническим писателем в данном контексте понимается "специально обученный человек", который с большей долей вероятности может вполне являться и разработчиком.
К проектной документации относится информация, начиная с технического задания, заканчивая описанием функциональной части проекта, которые служат инструкцией для пользователя.
К проектной документации относится собственно и само проектирование. Можете ознакомиться с технологией UML, почитать что такое ERD, IDEF, Use Case и т.п. диаграммы. Для разработки проекта большой командой — необходимо придерживаться некоторых стандартов. Представления документации, созданной в рамках проектирования системы в представленном на диаграммах, формализованном виде — позволяет облегчить жизнь разработчикам, пользователям, заказчикам и т.п.
Если я не ошибаюсь, то для тендерных проектов сначала создается проектная документация, на которую тоже может быть, кстати, выставлен тендер. Затем, на основании проектной документации выставляется требование на разработку.


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


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

Это компетенция технически подкованного специалиста. Документацию к проекту кому-то писать надо. В данном случае для этого выделена отдельная позиция, чтобы разгрузить разработчиков.

Дожили. Теперь даже ТЗ и другие документы по проекту, многие, не понимают зачем нужны, а ведь раньше, со школы, учили, что «правильно поставленная задача — это половина решения»…

Работать без ТЗ в наше время не приемлимо ни для разработчик(а/ов), ни для заказчика. Так называемая, правильная постановка задачи — должна быть описана в ТЗ)))

Работать без ТЗ или на основании ТЗ, разные истории) Вполне можно писать ТЗ параллельно с разработкой. Точнее в догонку, как только тот или иной кусок функциональности разработан и не планируется меняться в ближайшее время :)

Ну, если вы имеете ввиду такие методологии, как, например, agile и т.п., то no comment…
Но согласитесь, крайне не приятная ситуация, когда на поздних стадиях разработки вам говорят — ребят, давайте переделаем)))
Исходя из этого я очень часто стараюсь как можно более детально провести декомпозицию системы на компоненты и подсистемы… иначе можно очень круто встрять)))
Ну и вспомним анекдот про сферического коня в вакууме, конечно)))
Мой идеальный вариант иметь сначала ТЗ на проектирование с описанием функциональных требований. Пусть даже это будет только создание основной концепции. И только после этого разработка.
Хотя сегодняшние реалии таковы, что если это типовой проект, то решение чаще всего уже имеется в том или ином виде.
Все зависит от сегмента с которым работает конкретный участник процесса

Зарегистрируйтесь на Хабре , чтобы оставить комментарий

Публикации

Истории