Особенности процесса разработки технической документации

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

О техдокументации

Определение

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

Задачи техдокументации

Разработка технической документации включает следующие задачи:

1. Организация обмена знаниями, их контроль. С помощью проработанной базы данных ТД с допфункцией тестирования работников можно управлять корпоративным образованием, обеспечивать быстрый онбординг новичков, сокращать риски потери данных из-за увольнения.
2. Коммуникация между отделами. Главное следить за актуальностью ТД и полнотой сведений о каждом аспекте разработки. Это позволит каждому работнику изучить планы, требования и сэкономит ресурсы команды.
3. Управление качеством, решение вопросов стандартизации. При помощи готовых шаблонов, сертификата безопасности, стандартов можно облегчить работу и заложить хорошую основу для будущего. А история сложных кейсов, с которой сталкивались раньше, поможет избежать повторения негативного опыта.

Участники проекта

Разработка комплекса технической документации – это работа команды. Участвовать могут следующие специалисты:

1. SME – эксперты по вопросам, продуктам, сфере. Могут качественно проконсультировать, проверить итоги выполненной работы.
2. Разработчики продукта. Убедят, что техаспекты документов, которые относятся к коду, соответствуют действительности. Также помогут в разработке системы обучения. Это актуально, когда нужно быстро вовлечь новых сотрудников в процесс.
3. Проект-менеджеры. Координируют работу команды и контролируют сроки.
4. Дизайнеры – изучают и проектируют взаимодействие пользователя с продуктом, предоставляют полезную информацию.
5. Техписатели. Работают совместно со всеми названными выше специалистами. В результате техдокументация получается более качественной.

Что включает

ТД состоит из:

• стандартов компании;
• техрегламентов;
• инструкций;
• руководства;
• паспортов;
• формуляров;
• ТУ;
• ГОСТов;
• спецификаций;
• чертежей, схем;
• описания процесса сертификации и др.

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

Кому требуется 

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

1. Техусловий, определяющих производственный процесс.
2. Стандарта организации, схожего с техническими условиями, но охватывающего бОльшую область.
3. Техноинструкций, устанавливающих поэтапность задач, производственный алгоритм, процесс по типу ремонтных работ, переработок.
4. Руководства по использованию и других.

Какие виды бывают

Основных всего два:

1. Конструкторская. Состоит из РЭ прибора, программного обеспечения, паспорта изделия, технических условий.
2. Технологическая. В ней указаны данные о создании продукта, ремонта оборудования, изменений программного кода. 

Какие документы нужны для разработки 

Чтобы создать ТД, нужно предварительно подготовить:

• все данные о проекте;
• личные пожелания;
• всю информацию об организации.

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

Что следует учесть при технологии разработки технической документации

Стоит учитывать следующие негласные правила:

1. Документация не всегда нужна.Это касается программ разового использования. Например, небольших скриптов.
2. Техспецификация требуется не всегда. Если программисту удается хорошо создать код, то пользователь понимает, зачем ему продукт только по названию. При использовании разработчиком API/фреймворка, документы позволят программисту применить классы и методы, если невозможно прочесть исходный код.
3. Точность – одно из главных показателей ТД. Важно выразить свои идеи ясно – дать краткие определения всем фрагментам кода.
4. Емкие сопроводительные проекты. Комментарии от разработчика должны быть сухими, без шуток, замысловатых выражений, любых украшений речи. Иначе это только запутает коллег.
5. В техдокументации не должно быть старого кода. Это может запутать разработчика. Любой документ, который не относится к ПО, лучше исключить. При сомнениях воспользуйтесь системой контроля версий.

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

Где писать

Создать xml-код можно в Word или Google Docs. Последний вариант отличается наличием онлайн-доступа. Плюс в том, что можно изменять данные, если информация больше не актуальна.

Также можно написать код в программе. В этом случае разработчики смогут получить данные по коду. Проще это сделать с помощью комментариев от программистов при разработке кода. При выборе С# есть два типа комментариев:

• однострочные с вместимостью двух-трех параметров;
• многострочные с указанием нужной информации.

Также комментарии можно написать с помощью кода  XML. Для его вставки программисту придется перед добавлением названия класса, поля, свойств указать слэш «///”. Это позволит создать в авторежиме два элемента:

1. Summary. В этой строке прописывают общий комментарий с данными о необходимости метода и класса.
2. Param. Здесь разработчик указывает, какое значение нужно передать.

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

Жизненный цикл создания документации

 

Любой проект проходит стадии развития – от идеи до реализации. То же касается и документации.

Представьте, что перед вами стоит цель – написание техдокументации для промсектора. Этот документ является составляющей конструкторской документации. Инструкция может быть самостоятельной или как приложение к техусловиям.

Ее жизненный цикл будет выглядеть так:

1. Планирование. Нужно поставить задачу, варианты оценки ее достижения, определить ЦА, период для реализации, обозначить участников процесса. 
2. Исследовательская деятельность. Необходимо просмотреть все данные, провести интервью, проконсультироваться с экспертами. Также не забудьте протестировать продукцию.
3. Черновик. Нужно собрать черновой вариант бумаги, проработать визуал, структу, формат.
4. Резервирование. Необходимо передать документацию на проверку экспертам/ответственным лицам, получить заключение и поработать над правками.
5. Редактирование. Нужно привести инструкцию в надлежащий вид. При этом опираться стоит на стандарты, регламент компании. Также стоит вычитать текст на ошибки, неверные толкования, трудночитаемые фразы. После этого отформатировать и оформить.
6. Согласование. Необходимо передать результат на проверку.
7. Публикация. Нужно разместить документацию в формате, который доступен для конечного пользователя.
8. Поддержка. Не лишним будет отслеживать взаимодействие пользователей с техдокументом, корректировать. 

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

Методы разработки технической документации

Важно внимательно подходить к методам формирования, оформления ТД. От этого будет зависеть успех продукта. Современные методы разработки основаны на следующих принципах и подходах.

Один источник

Данные нужно собрать в единый формат и поместить в общее хранилище.

Плюсы такого подхода:

• возможность повторного использования контента;
• сокращение затрат;
• значительное упрощение сопровождения.

DocOps

Речь идет о лучших процессах, инструментах.Так можно автоматизировать процессы и сократить затраты. 

Минимализм

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

Автоматизация

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

Графика и видео

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

Разработка в коллективе

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

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

Синхронизация

Этот вариант обеспечивает админподдержка на прикладном уровне. Благодаря взаимному «наложению» процессов удается синхронизировать выпуск документации-сопровождения с релизными периодами продукции.
Передовые приемы являются дополнительными средствами в процессе разработки технической документации. Самое главное – предоставлять полезные сведения. Для этого нужно анализировать обратную связь.