Что такое техническая документация кратко

Обновлено: 07.07.2024

ГОСТ Р ИСО 11442-2014

НАЦИОНАЛЬНЫЙ СТАНДАРТ РОССИЙСКОЙ ФЕДЕРАЦИИ

ТЕХНИЧЕСКАЯ ДОКУМЕНТАЦИЯ НА ПРОДУКЦИЮ

Technical product documentation. Document management

Дата введения 2016-01-01

Предисловие

1 ПОДГОТОВЛЕН ООО "НИИ экономики связи и информатики "Интерэкомс" (ООО "НИИ "Интерэкомс") на основе собственного перевода на русский язык англоязычной версии стандарта, указанного в пункте 4

2 ВНЕСЕН Техническим комитетом по стандартизации ТК 100 "Стратегический и инновационный менеджмент"

4 Настоящий стандарт идентичен международному стандарту ИСО 11442:2006* "Техническая документация на продукцию. Управление документацией" (ISO 11442:2006 "Technical product documentation - Document management", IDT).

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

При применении настоящего стандарта рекомендуется использовать вместо ссылочных международных стандартов соответствующие им национальные стандарты, сведения о которых приведены в дополнительном приложении ДА

5 ВВЕДЕН ВПЕРВЫЕ

6 ПЕРЕИЗДАНИЕ. Декабрь 2018 г.

1 Область применения

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

2 Нормативные ссылки

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

* Таблицу соответствия национальных стандартов международным см. по ссылке. - Примечание изготовителя базы данных.

ISO 10209-1, Technical product documentation - Vocabulary - Terms relating to technical drawings, product definition and related documentation (Техническая документация на продукцию. Словарь. Термины, относящиеся к техническим чертежам, определение продукции и связанная с этим документация)

ISO 16016, Technical product documentation. Protection notices for restricting the use of documents and products (Техническая документация на продукцию. Защитные уведомления, ограничивающие использование документов и продуктов)

3 Термины и определения

В настоящем стандарте применены термины по ИСО 10209-1, а также следующие термины с соответствующими определениями:

3.1 анализ (analysis): Часть процесса разработки продукции, связанного с подготовкой спецификации требований.

3.2 фаза утверждения (approval phase): Стадия, на которой содержание документа формально проверяется и утверждается.

3.3 архивная копия документа (archive master): Репродукция документа для длительного хранения в соответствующем формате кодирования.

3.4 фаза архивирования (archiving phase): Стадия, на которой документы на продукцию передаются из хранилища активных документов в исторический архив.

3.5 авторизация (authorization): Определение привилегий для конкретного идентифицированного пользователя в части доступа к указанным операциям.

3.6 эскизное проектирование (basic design): Часть процесса разработки продукции, предполагающая оценку проектных предложений и подготовку базовой проектной документации.

3.7 концептуальное проектирование (conceptual design): Часть процесса разработки продукции, включающего подготовку проектных спецификаций и проектного предложения.

3.8 фаза создания (creation phase): Стадия, на которой выполняются работы по проектной документации.

3.9 техническое проектирование (detailed design): Часть процесса разработки продукции, включающая разработку конечного определения продукта.

3.10 документ (document): Фиксированное и структурированное количество информации, разрабатываемое и передаваемое как целостная единица между пользователями и системами.

3.11 репродукция документа (document replica): Точная или максимально приближенная копия оригинального документа.

3.12 опубликованный документ (document issue): Идентифицированная версия документа.

3.13 статус документа (document status): Шаг (стадия) жизненного цикла готового документа.

3.14 оригинальный документ (original document): Документ, содержащий техническое описание (определение) продукции и формирующий базу для его будущих изменений.

3.15 выпустить (документ) (release): Создать документ, пригодный для использования по предназначению.

3.16 фаза выпуска (release phase): Стадия выпуска готового документа.

3.17 точность воспроизведения репродукции (replica fidelity): Качественный показатель репродукции документа в части передачи информации, содержащейся в оригинальном документе.

3.18 уведомление о пересмотре (revision notice): Часть документа (отдельный документ), содержащая информацию о пересмотре документации на продукцию.

3.19 фаза пересмотра (revision phase): Стадия, на которой производятся изменения документации на продукцию.

3.20 спецификация требований (specification of requirements): Совокупность общих требований, официальных требований (например, законов, постановлений, директив) и корпоративных требований.

3.21 хранение/активная фаза (storage/active phase): Стадия, на которой производится сохранение активной документации.

3.22 подписанный документ (signature document): Копия оригинального документа, имеющая утверждение, требуемое заказчиком, и представляющее собой основание для последующих утверждений.

3.23 рабочая копия (viewing copy): Репродукция документа, предназначенная для просмотра, внесения изменений и изготовления печатных копий.

4 Оригинальные и воспроизведенные документы

4.1 Общие положения

Следующие положения помогут при пользовании системы документации и облегчат понимание принципов ее работы.

4.2 Оригинальный документ

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

Каждый утвержденный оригинальный документ хранят в архиве оригиналов (электронном хранилище). Доступ к данному архиву регулируют путем проведения специальных процедур "входной/выходной учет (регистрация)". Оригинальный документ в электронной форме хранится в идентифицированном формате на специальном носителе информации (например, магнитном или оптическом). Если документы оформляют вручную, то носителем представительных данных (рисунок, текст) может быть удобный для воспроизведения носитель, например, бумага или пленка. Любой пересмотр должен быть произведен в строгом соответствии с оригинальным документом.

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

4.3 Подписанный документ

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

4.4 Рабочая копия

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

4.5 Архивная копия документа

Для документации, представленной в электронной форме, репродукция документа (см. 4.6) необходима для обеспечения его длительного хранения. Репродукция сохраняется в проверенном нейтральном формате. Формат архивной копии документа должен быть легко интерпретируемым и воспроизводимым для определенного периода времени (он может зависеть от срока службы продукции). Представление продукции должно быть открытым и независимым от перспективных версий используемых электронных средств и программного обеспечения.

Примечание - Типовые форматы цифровой архивной копии документа: TIFF (растровый), SGML, XML и STEP.

4.6 Репродукция документа, точность воспроизведения репродукции

Репродукция документа - это точная (почти точная) копия оригинального документа. Репродукция может утрачивать часть информации по сравнению с источником. Степень точности воспроизведения информации классифицируют с учетом возможности репродукции документа передавать информацию, содержащуюся в оригинальном документе.

Значения степени точности воспроизведения репродукции классифицируют следующим образом:

- клонированное воспроизведение (точная копия);

- эквивалентное воспроизведение (с некоторой потерей информации для целевого эквивалента);

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

5 Фазы работы с проектной документацией

5.1 Общие положения

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

Как правило, техническое задание представляет собой спецификацию общих требований, частных требований и корпоративных требований.

Проектные спецификации рассматриваются как база для последующих разработок. Данные спецификации могут содержать возможные функциональные решения и (или) представления формы. Они составляют основу для оценки одного или нескольких рассматриваемых предложений. Результатом данной оценки и является базовая проектная документация.

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

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

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

Технический рисунок – это рисунок (3D), выполненный на глаз, от руки, без применения измерительного и чертёжного инструмента. Технический рисунок выполняется по законам аксонометрических проекций начертательной геометрии.

Схема – это представление некоторого объекта в общих, главных чертах с помощью условных обозначений. С помощью схем может быть представлен и внешний вид объекта, и его структура.

Основная и дополнительная литература по теме урока

Теоретический материал для самостоятельного изучения

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

Техническая документация – это набор графических и текстовых документов. Они используются при проектировании, конструировании, изготовлении или использовании (эксплуатации) каких – либо продуктов труда: промышленных изделий, зданий и сооружений, услуг, программного. Техническая документация задаёт весь технологический процесс производства: получения, изготовления, использования, ремонта.

Вся техническая документация делится на конструкторскую и технологическую.

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

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

После составления рабочих чертежей на изделие осуществляется технологическая подготовка производства. Она включает в себя разработку технологической документации на изготовление изделия.

В нашей стране принята Единая система технологической документации (ЕСТД) и Единая система конструкторской документации (ЕСКД). Эти системы устанавливают виды и формы технологических документов: технологические карты, маршрутные карты, операционные карты, а также конструкторских документов (чертежей, эскизов, технических рисунков, схем).

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

На промышленных предприятиях инженеры-технологи разрабатывают и внедряют технологические процессы и режимы производства. Они составляют планы размещения оборудования, организации рабочих мест, рассчитывают производственные мощности и загрузку оборудования, технические нормы расхода сырья, материалов, энергии, экономическую эффективность технологических процессов. Разрабатывают технологическую документацию, методы технического контроля и испытания продукции, технические задания на проектирование приспособлений, оснастки и инструмента. Участвуют в экспериментальных работах по освоению технологических процессов и внедрению их в производство. Анализируют причины брака, участвуют в разработке мероприятий по его устранению. Контролируют соблюдение технологической дисциплины и правил эксплуатации оборудования, разрабатывают мероприятия по повышению эффективности производства и принимают участие в их проведении. Деятельность инженера – технолога представляет собой работу с применением знаний технологии производства продукции предприятия, конструкции изделий или состава продукта, технологического оборудования и принципов его работы, технологических, процессов и режима производства, стандартов и технических условий, видов брака и способов его предупреждения, основ систем автоматизированного проектирования, порядка и методов проведения патентных испытаний.

Такой специалист должен иметь высшее или среднее специальное образование.

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

Примеры и разбор решения заданий тренировочного модуля

Задание 1. Когда используют технологическую документацию? Из приведённых ниже вариантов выберите правильные.

При отгрузке
При проектировании
При изготовлении
При смещении
При использовании

Правильный ответ: 2, 3, 5.

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

Формы документов: Техническая документация

Судебная практика: Техническая документация

Статьи, комментарии, ответы на вопросы: Техническая документация

Путеводитель по судебной практике. Подряд. Общие положения 1.4. Вывод из судебной практики: Непредоставление подрядчиком (субподрядчиком) исполнительной (технической) документации само по себе не освобождает заказчика (генерального подрядчика) от оплаты работ.

Открыть документ в вашей системе КонсультантПлюс:
"Гражданское право: В 2 т.: Учебник"
(том 2)
(3-е издание, переработанное и дополненное)
(под ред. Б.М. Гонгало)
("Статут", 2018) Техническая документация - это совокупность документов, определяющих объем, содержание работ и другие предъявляемые к ним требования, в соответствии с которыми подрядчик обязан выполнить работу. По существу, техническая документация отражает задание заказчика. Если речь идет о возведении объектов капитального строительства, то техническая документация включает в себя проектную документацию, состав которой определен п. 12 ст. 48 ГрК (схема планировочной организации земельного участка, выполненная в соответствии с градостроительным планом земельного участка; архитектурные решения; конструктивные и объемно-планировочные решения; сведения об инженерном оборудовании, о сетях инженерно-технического обеспечения, перечень инженерно-технических мероприятий, содержание технологических решений и т.п.). Объем проектной документации в отношении объектов капитального строительства весьма значителен и, как правило, подлежит экспертизе, в том числе в случаях, предусмотренных законом, - государственной экспертизе (ст. 49 ГрК).

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

В нашей новой статье мы расскажем о том, какую пользу и преимущества предоставляет грамотная техдокументация. Вы узнаете, какая документация считается качественной и что она должна включать, какие виды и форматы таких материалов существуют и чем они отличаются друг от друга. Кроме того, мы расскажем про профессию технического писателя (техрайтера), что он должен уметь и какая сейчас ситуация на рынке этих специалистов.

Что такое техническая документация на ПО? Ее виды и форматы

Документация на программное обеспечение (software documentation) – это комплекс документов, в которых подробно описываются технические характеристики и потребительские качества ПО, а также сведения о процессе его разработки, применения и сопровождения.

Пакет документации на ПО включает не только технические материалы, но и множество других видов документов. К ним относятся руководства, инструкции и справки для пользователей, обзоры программного обеспечения, спецификации, методики тестирования и т.д. Для удобства классификации вся эта документация делится на 4 категории:

Проектная (архитектурная). Описывает основные положения, цели, задачи и этапы проекта, которые применяются при создании программного обеспечения и его рабочей среды. Представляет собой общий обзор ПО, предназначенный, прежде всего, для работающих над проектом специалистов.
Техническая. Иногда так называют абсолютно всю документацию для программного обеспечения, хотя это не совсем верно. Непосредственно техдокументация включает описание программного кода и выполняемых им функций, структур данных, алгоритмов, API и интерфейсов. Кроме того, в ней подробно отображается процесс разработки ПО, принцип его действия и порядок эксплуатации. Часто такие материалы поставляются в комплекте с исходным кодом программы или же встраиваются в него в виде комментариев. Для упрощения создания и обновления техдокументов используют специальные шаблоны или делают это автоматизировано при помощи генераторов документации (Javadoc, Doxygen, NDoc и т.д.).
Пользовательская. Если первые два вида материалов ориентированы на специалистов, то эта категория предназначена для пользователей программного обеспечения. В ней нет сложных технических описаний кода и принципов его работы, вместо этого она сосредоточена на описании функций ПО и правил его эксплуатации. Среди наиболее распространенных форматов пользовательской документации можно отметить краткое руководство пользователя (User's Guide) и подробный справочник пользователя (User's Reference). Также она нередко содержит инструкцию по решению проблем и ответы на часто задаваемые вопросы.
Маркетинговая. Еще одним из основных видов документации на ПО являются маркетинговые материалы, которые помогают привлечь внимание целевой аудитории к продукту, рассказать о его предназначении, возможностях и преимуществах. В отличие от пользовательской, маркетинговая документация гораздо более краткая. Часто она состоит из одного рекламного буклета, предназначенного для ознакомления пользователя с программой или приложением.

Какой должна быть качественная документация?

Прежде всего, она должна соответствовать определенному набору стандартов. А именно, таким, как:

Структурированность. Наличие четкой структуры является одним из важнейших требований к технической документации. Она должна быть логически упорядочена в разделы и подразделы, иметь абзацы, списки и другие элементы форматирования текста. Если речь идет о пользовательских мануалах, то одним лишь текстовым описанием здесь не обойтись – его нужно дополнять скриншотами программы в высоком качестве. Не менее популярными считаются видео-мануалы, которые, впрочем, не могут полностью заменить собой текстовые материалы.
Единообразие. Вся документация на программное обеспечение должна быть оформлена в едином формате, включая как проектные и технические документы для сотрудников, так и материалы для пользователей. Кроме того, в ходе ее составления следует сверяться с другими документами, выпущенными вашей компанией, чтобы придерживаться единого корпоративного стиля. Нелишним также будет заранее стандартизировать процесс подготовки документации, чтобы избежать каких-либо расхождений в дальнейшем.
Информативность. Еще одним важным признаком качественной документации на ПО является ее понятность и информативность. Для достижения этой цели нужно уметь соблюсти баланс между объемом данных и простотой их изложения. Ухудшить этот показатель может как недостаток, так и избыток информации, особенно, когда дело касается документации для пользователей. С одной стороны, не нужно делать ее излишне поверхностной и упрощенной, а с другой нельзя допустить чрезмерного усложнения материала.
Релевантность. Хорошая техническая документация обязательно должна быть предназначена для определенной целевой аудитории. Создание общего универсального руководства для разработчиков и пользователей – это интересная, но трудновыполнимая задача, которая вряд ли будет под силу даже опытному техрайтеру. Перед разработкой материалов желательно определить круг сотрудников или клиентов, для которых они будут максимально полезны и интересны. Также необходимо иметь представление об уровне подготовки аудитории и о том, какие ее задачи и проблемы сможет решить эта документация.

Что такое техническое задание и технический проект?

Как правило, всю техническую документацию необязательно прописывать до начала разработки программного обеспечения. Чаще всего современные IT-проекты создаются по методологии Agile, а работа над ними ведется по спринтам, что позволяет писать документацию параллельно с процессом разработки.

Однако есть несколько документов, которые в идеале должны быть подготовлены до старта разработки ПО: к ним относится техническое задание (ТЗ) и технический проект (ТП).

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

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

Кто такой технический писатель? Особенности, задачи и проблемы этой профессии

Разработкой технической документации на программное обеспечение занимается технический писатель (technical writer, техрайтер). Он готовит практически все виды таких материалов, включая руководства и справочники для пользователей, технические проекты для специалистов, маркетинговые тексты и т.д. К должностным обязанностям техрайтера относятся:

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

В идеале профессиональный технический писатель – это гуманитарий с техническим образованием, который понимает основы IT-разработки, владеет специализированной терминологией, знает некоторые языки программирования и языки разметки, а также средства автоматизации процессов документирования. При этом он должен иметь определенные филологические навыки, чтобы составлять технический материал кратко, информативно и понятно как для специалистов, так и для обычных пользователей.

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

Подводим итоги

Документация на программное обеспечение включает 4 основных вида материалов: проектные, технические, пользовательские и маркетинговые. Ее можно составлять параллельно с разработкой ПО, заранее нужно подготовить только техническое задание и технический проект. Качественная документация обязательно должна иметь четкую структуру, быть оформлена в едином формате, быть понятной и информативной как для специалистов, так и для пользователей.

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

Читайте также: