Что такое компьютерная документация
Документа́ция на программное обеспечение — печатные руководства пользователя, диалоговая (оперативная) документация и справочный текст, описывающие, как пользоваться программным продуктом [1] .
Документ — элемент документации: целевая информация, предназначенная для конкретной аудитории, размещенная на конкретном носителе (например, в книге, на диске, в краткой справочной карте) в заданном формате [1] .
Программный документ — документ, содержащий в зависимости от назначения данные, необходимые для разработки, производства, эксплуатации, сопровождения программы или программного средства [2] .
Примечания
- ↑ 12 ГОСТ Р ИСО/МЭК 15910-2002 — Процесс создания документации пользователя программного средства
- ↑ГОСТ 19781—90 Единая система программной документации. Обеспечение систем обработки информации программное
Смотреть что такое "Документация на программное обеспечение" в других словарях:
Программное обеспечение — Запрос «Software» перенаправляется сюда; см. также другие значения … Википедия
программное обеспечение — 01.01.80 программное обеспечение (в области электросвязи) [software ]: Программы ЭВМ, процедуры, правила и любая сопутствующая документация, имеющие отношение к работе аппаратуры, сети электросвязи или другого… … Словарь-справочник терминов нормативно-технической документации
программное обеспечение (ПО) — 3.34 программное обеспечение (ПО) (software): Программы (т.е. набор упорядоченных команд), данные, правила и любая связанная с этим документация, имеющая отношение к работе компьютеризированной системы контроля и управления. [МЭК 62138, пункт… … Словарь-справочник терминов нормативно-технической документации
ГОСТ Р МЭК 60880-2010: Атомные электростанции. Системы контроля и управления, важные для безопасности. Программное обеспечение компьютерных систем, выполняющих функции категории А — Терминология ГОСТ Р МЭК 60880 2010: Атомные электростанции. Системы контроля и управления, важные для безопасности. Программное обеспечение компьютерных систем, выполняющих функции категории А оригинал документа: 3.25 N версионное программное… … Словарь-справочник терминов нормативно-технической документации
Документация — Документация это совокупность данных и документов. В узко профессиональном значении Документация (документирование) процесс отбора, классификации, использования и распространения документов. Работа специалиста по подбору документации… … Википедия
ПРОГРАММНОЕ СРЕДСТВО — 6. ПРОГРАММНОЕ СРЕДСТВО по ГОСТ 28806 90. Источник: РБ 004 98: Требования к сертификации управляющих систем, важных для безопасности атомных станций … Словарь-справочник терминов нормативно-технической документации
обеспечение — Процесс скоординированного управления по обеспечению всех материалов и ресурсов, требуемых для эксплуатации изделия. Источник: ГОСТ Р 53480 2009: Надежность в технике. Термины и определения оригинал документа … Словарь-справочник терминов нормативно-технической документации
Стадия «Рабочая документация» — 2.6. Стадия «Рабочая документация» 2.6.1. Задачей стадии является разработка технической рабочей документации, обеспечивающей выполнение работ по вводу АС в действие. На данном этапе должны быть также все документы, необходимые при эксплуатации… … Словарь-справочник терминов нормативно-технической документации
Canon EOS 30D — Тип цифровой зеркальный фотоаппарат Матрица КМОП 22,5 × 15,0 мм (Kf = 1,6) … Википедия
Canon EOS 600D — Canon EOS Digital Rebel T3i Canon EOS Kiss X5 Тип DSLR … Википедия
Законодательство трансформируется, подстраиваясь или определяя современные тенденции, и из-за этого, так или иначе, документооборот постепенно, но неуклонно, переходит в электронный вид. Это удобнее, быстрее и практичнее работы с бумагой. Чтобы электронный документ имел юридическую силу, необходимо соблюдать ряд правил, которые рассмотрим далее.
Когда составлять техническую документацию
Выше я описала идеальный процесс создания программного обеспечения, но иногда некоторые документы технического проекта составляют уже после этапа разработки.
Есть проекты, в которых важно иметь полную документацию до начала работ. Это касается решений с высокими требованиями к безопасности, соблюдению законодательства и т. д. Например, мобильные приложения для банков. В этом случае важно сначала продумать все детали системы (информационная безопасность клиентов и самого банка, соответствие законам). На это уйдет больше времени, но позволит избежать финансовых и репутационных рисков.
Если разработка идет по методологии Agile, то нет смысла прописывать всю документацию до старта работ. Если заказчику важно работать по спринтам и контролировать ход разработки, документацию можно дописывать параллельно основному процессу.
В нашей компании возможны оба варианта — мы умеем адаптироваться под условия и пожелания заказчика.
На сегодняшний день технический писатель не самая распространенная специальность, но для серьезной компании-разработчика такой сотрудник не менее важен, чем, например, аналитик.
Техническая документация обязательно разрабатывается для госзаказчиков, она необходима и для долгосрочных проектов, на которых с бОльшей вероятностью могут меняться подрядчики. Имеет смысл создавать технический проект для ноу-хау технологий и проектов высокой сложности — документация понадобится отделу QA, чтобы отличить баги и фич.
Содержание
Примечания
- ↑Adams, PeterPageMaker Past, Present, and Future (англ.) (16 March 2004). Архивировано из первоисточника 24 марта 2012.Проверено 14 августа 2009.
Информация должна быть проверяема, иначе она может быть поставлена под сомнение и удалена.
Вы можете отредактировать эту статью, добавив ссылки на авторитетные источники.
Эта отметка установлена 13 мая 2011.
Привет, Хабр! Меня зовут Богданова Софья, я технический писатель в компании Documentat, где мы занимаемся разработкой технической документации для различных IT-проектов.
За все время работы приходилось сталкиваться с кучей разной документации, но сейчас я плотно засела с документированием по ГОСТу. Собственно, о чем и будет этот пост.
Непросвещенному читателю ГОСТ может показаться канцелярскими дебрями, где для разъяснения одного предложения надо найти остров, на острове дуб, под дубом сундук и далее по списку. Но на самом деле, если разобраться и вникнуть в ГОСТовскую кухню, то с этим можно жить и даже активно пользоваться.
Какая техническая документация нужна разработчику
Рассмотрим идеальный с точки зрения ГОСТа процесс разработки системы.
Все начинается с требований заказчика или заинтересованных лиц, которые необходимо выявить и обязательно зафиксировать в документе «Техническое задание».
Техническое задание — это документ, регламентирующий бизнес-цели, общее описание системы, объем работ, границы проекта, а также порядок разработки, оценки и приемки. Данный документ отвечает нам на вопрос «что нужно сделать?» и фактически является постановкой задачи.
Аналитик составляет ТЗ и согласует его со всеми заинтересованными сторонами. После того как собраны и утверждены все требования, можно приступать к созданию прототипов будущей системы и разработке программного обеспечения.
На этом этапе начинается разработка макетов, сценариев, архитектуры и др. Раз уж мы говорим об эталонном процессе разработки, то все это должно быть описано в техническом проекте, который также использует часть информации из ТЗ.
Технический проект — это совокупность документов, описывающих и обосновывающих все подходы, методы, архитектурные и технические решения, применяемые для создания системы. Например, в технический проект включают макеты интерфейсов, описание протоколов для интеграции со смежными системами и оборудованием, пользовательские сценарии, описание алгоритма и их формирование, структура серверов и баз данных, а также другие требования к системе и ее взаимодействию с другими внешними системами.
это далеко не все: существует много стандартов для написания технической документации, и для каждой страны они свои. В отечественных стандартах есть отдельно ГОСТ на создание автоматизированных работ и на программное изделие. Например, технический проект по ГОСТу 19 «Единая система программной документации» может включать в себя следующий перечень работ:
- уточнение структуры входных и выходных данных,
- разработка алгоритма решения задачи,
- определение формы представления входных и выходных данных,
- определение семантики и синтаксиса языка,
- разработка структуры программы,
- окончательное определение конфигурации технических средств,
- разработка плана мероприятий по разработке и внедрению программ,
- разработка пояснительной записки,
- согласование и утверждение технического проекта.
Теперь, когда есть четкое понимание архитектуры, функциональности и дизайна проекта, можно перейти к разработке системы и ее тестированию.
На этапе тестирования, помимо проверки работоспособности системы, проверяется также выполнение всех требований, зафиксированных в документах, что позволяет разрешить спорные ситуации с заказчиком.
Кто такой технический писатель
Строго сформулированного перечня должностных обязанностей технического писателя не существует: каждая компания формирует его сама, а иногда возлагает на такого специалиста и дополнительные задачи. Поэтому иногда бывает сложно даже определить род деятельности технического писателя. В нашей компании такой специалист составляет документацию, необходимую для дальнейшей разработки программного обеспечения.
Для этого он собирает информацию и материалы от участников проекта и документирует эти данные согласно требованиям заказчика, в том числе и в соответствии с ГОСТами. Речь идет о ГОСТ 19 «Единая система программной документации» и ГОСТ 34 «Информационная технология. Комплекс стандартов на автоматизированные системы». Также технический писатель следит за актуальностью технической информации, если это необходимо на длительных и сложных проектах.
Что говорит закон об электронных документах?
Понятие документа закрепляет Федеральный Закон от 29.12.1994 № 77-ФЗ (действующая редакция от 03.07.2016) «Об обязательном экземпляре документов». Так, документ – материальный носитель, который содержит текстовую, графическую, аудио- или видеоинформацию, а также реквизиты владельца, предназначенную для передачи, хранения и использования физическими и юридическими лицами.
Соответственно, с точки зрения закона бумажные и электронные документы практически не отличаются, только электронный формат подразумевает хранение информации на CD-дисках, FLASH- или USВ-накопителях, винчестерах, а бумажный, соответственно, на бумаге. Но это не значит, что электронный и бумажный документ – тождественные понятия.
Термин электронного документа (далее ЭД) дан в Федеральном законе от 27.07.2006 № 149-ФЗ (действующая редакция от 18.03.2019) «Об информации, информационных технологиях и о защите информации». Так, ЭД – это информация, изначально созданная и представленная в электронном виде в формате, который позволяет обработать ее с помощью компьютера или других электронно-вычислительных систем.
Полезное
История
Начало компьютерной вёрстке было положено в 1985 году, когда вышла созданная корпорацией Aldus программа PageMaker [1] и персональный лазерный принтер LaserWriter компании Apple Computer. Возможность создания WYSIWYG макетов страницы на экране монитора с последующей распечаткой на принтере была новой как для компьютерной индустрии, так и для типографского дела. Термин «desktop publishing» был предложен Полом Брейнердом, основателем Aldus Corporation.
Ранние системы компьютерной верстки на сегодняшний день выглядят весьма примитивными. Связка PageMaker-LaserWriter-Macintosh 512K была не совсем стабильной, часто зависала, использовался чёрно-белый экран, невозможно было контролировать кернинг, трекинг и другие важные для вёрстки параметры. Но в то время отзывы о системе были одобрительными.
Технологии, разработанные Adobe Systems, заложили фундамент для дальнейшего развития компьютерной вёрстки. Принтеры LaserWriter и LaserWriter Plus содержали во встроенной ROM-памяти масштабируемые шрифты от Adobe.
В 1986 году вышла программа Ventura Publisher для компьютеров под ОС MS-DOS. В то время как PageMaker имитировала процесс создания макета страницы вручную, Ventura Publisher автоматизировала этот процесс путем использования тэгов (tags) и таблиц стилей (style sheet), что позволило автоматизировать процесс создания индексов и элементов макета страницы. Таким образом Ventura Publisher была удобнее PageMaker при создании макетов книг и многостраничных документов.
В это время компьютерная верстка воспринималась как непригодная для широкого использования, во многом благодаря пользователям, которые использовали плохо организованные макеты. Тем не менее, профессиональное использование технологий компьютерной вёрстки позволяло уже тогда получить хорошие результаты. Например, журнал Info magazine в конце 1986 года стал первым полноцветным изданием, подготовленным методами компьютерной вёрстки.
Улучшение и расширение инструментов для работы с текстом и графикой для компьютеров привлекло внимание профессионального печатного сообщества к системам компьютерной вёрстки. Переломным моментом стало появление в 1990-х годах программы QuarkXPress, а также расширение базы компьютерных шрифтов. QuarkXPress стала доминирующей системой на рынке. В начале 2000-х набрала популярность программа Adobe InDesign. Это произошло благодаря ее большим возможностям, а также интеграции с другими программами от Adobe, которые были доминирующими в сфере компьютерного дизайна, обработки изображений и фотографий, аудио- и видеоредактирования.
Ссылки
Кент Бек • Гради Буч • Фред Брукс • Barry Boehm • Уорд Каннингем • Оле-Йохан Даль • Том Демарко • Эдсгер Вибе Дейкстра • Дональд Кнут • Мартин Фаулер • Чарльз Энтони Ричард Хоар • Watts Humphrey • Майкл Джексон • Ивар Якобсон • Craig Larman • James Martin • Мейер Бертран • Дэвид Парнас • Winston W. Royce • James Rumbaugh • Никлаус Вирт • Эдвард Йордан • Стив Макконнелл
Моделирование данных • Архитектура ПО • Функциональная спецификация • Язык моделирования • Парадигма • Методология • Процесс разработки • Качество • Обеспечение качества • Структурный анализ)
CMM • CMMI • Данных • Function model • IDEF • Информационная • Metamodeling • Object model • View model • UML
- Техническая документация
- Программное обеспечение
- Разработка программного обеспечения
Wikimedia Foundation . 2010 .
Типы документации
Существует четыре основных типа документации на ПО:
- архитектурная/проектная — обзор программного обеспечения, включающий описание рабочей среды и принципов, которые должны быть использованы при создании ПО
- техническая — документация на код, алгоритмы, интерфейсы, API
- пользовательская — руководства для конечных пользователей, администраторов системы и другого персонала
- маркетинговая
Маркетинговая документация
Для многих приложений необходимо располагать рядом рекламные материалы, с тем чтобы заинтересовать людей, обратив их внимание на продукт. Такая форма документации имеет целью:
- подогреть интерес к продукту у потенциальных пользователей
- информировать их о том, что именно делает продукт, с тем чтобы их ожидания совпадали с тем, что они получат
- объяснить положение продукта по сравнению с конкурирующими решениями
Одна из хороших маркетинговых практик — предоставление слогана — простой запоминающейся фразы, иллюстрирующей то, что мы хотим донести до пользователя, а также характеризующей ощущение, которое создаёт продукт.
Часто бывает так, что коробка продукта и другие маркетинговые материалы дают более ясную картину о возможностях и способах использования программы, чем всё остальное.
Отличия образа документа от электронного документа
Следует различать образы документов и ЭД, поскольку установленные требования и критерии при оформлении к ним различаются, как и возможности последующего придания им юридической значимости и распространения
Под образом документа следует понимать версию информации, содержащуюся на материальном носителе. Наиболее простой пример – распечатанные ЭД. Они создаются только для удобства работы пользователей с электронными документами, так как дают им информацию о состоянии электронного документа в момент времени просмотра или в момент сохранения. Примером может послужить распечатка платежного поручения, с отметками банка о подписании в формате pdf, для каких-то срочных внутрикорпоративных нужд.
Стоит отметить, что даже если такие документы будут заверены надлежащим образом, во многих случаях (например, на суде), они все равно останутся копиями, которые будет необходимо подтверждать оригиналами. При этом все копии электронного документа в электронном виде являются оригиналами.
Что такое ГОСТ и зачем он нужен?
В далекие времена, когда изобретения ограничивались палкой-копалкой, потребности в их стандартизации особо не было. Когда производство приобрело большие масштабы, а сами изобретения стали сложнее по количеству составных частей и выполняемых ими функций, появилась необходимость всё это дело как-то привести если не в общий вид, то хотя бы в какой-то более менее стандартный.
Нужно это было прежде всего государству, чтобы ограничить выпуск некачественной продукции. Отсюда мы и получаем ГОСТ — государственный стандарт.
ГОСТов много, описывают они всё что можно и нельзя, но здесь мы будем говорить о стандартах написания технических документов.
“А зачем мне надо документы писать по каким-то стандартам? Я понятным языком напишу, все поймут отвечаю”
К сожалению, что понятно одному, может оказаться теорией струн для другого. Для того, чтобы любой желающий мог открыть документы и найти в них то, что так давно искал, были придуманы стандарты по их написанию.
Очень хорошо это демонстрирует техническое задание.
При разработке чего угодно важно отразить желаемый результат. Очень удобно разрабатывать, когда есть понимание, что же все-таки от тебя хотят. Свои желания все формируют по-разному и чтобы в потоке мыслей не потерять суть, а донести желаемое, удобно пользоваться готовым стандартом, который вы с разработчиком будете читать, а главное понимать одинаково.
В этом и есть основная суть ГОСТа — стандартизировать техническую документацию таким образом, чтобы она была понятна и разработчику, и конструктору, и даже тёте Ларисе из бухгалтерии.
Архитектурная/проектная документация
Проектная документация обычно описывает продукт в общих чертах. Не описывая того, как что-либо будет использоваться, она скорее отвечает на вопрос «почему именно так?» Например, в проектном документе программист может описать обоснование того, почему структуры данных организованы именно таким образом. Описываются причины, почему какой-либо класс сконструирован определённым образом, выделяются паттерны, в некоторых случаях даже даются идеи как можно будет выполнить улучшения в дальнейшем. Ничего из этого не входит в техническую или пользовательскую документацию, но всё это действительно важно для проекта.
Пользовательская документация
В отличие от технической документации, сфокусированной на коде и том, как он работает, пользовательская документация описывает лишь то, как использовать программу.
В случае если продуктом является программная библиотека, пользовательская документация и документация на код становятся очень близкими, почти эквивалентными понятиями. Но в общем случае, это не так.
Обычно, пользовательская документация представляет собой руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет инструкции о том что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение.
Существует три подхода к организации пользовательской документации. Вводное руководство (англ. tutorial ), наиболее полезное для новых пользователей, последовательно проводит по ряду шагов, служащих для выполнения каких-либо типичных задач. Тематический подход, при котором каждая глава руководства посвящена какой-то отдельной теме, больше подходит для совершенствующихся пользователей. В последнем, третьем подходе, команды или задачи организованы в виде алфавитного справочника — часто это хорошо воспринимается продвинутыми пользователями, хорошо знающими, что они ищут. Жалобы пользователей обычно относятся к тому, что документация охватывает только один из этих подходов, и поэтому хорошо подходит лишь для одного класса пользователей.
Во многих случаях разработчики программного продукта ограничивают набор пользовательской документации лишь встроенной системой помощи (англ. online help ), содержащей справочную информацию о командах или пунктах меню. Работа по обучению новых пользователей и поддержке совершенствующихся пользователей перекладывается на частных издателей, часто оказывающих значительную помощь разработчикам.
Как выбрать нужный ГОСТ?
Вообще, такой вопрос обычно возникает крайне редко, так как чаще всего заказчик или организация, в которой вы работаете, говорят вам: «Нужны документы по ГОСТ 19».
Но если вам приходится самому решать, какой ГОСТ лучше использовать, то я дам совет.
При разработке документации на IT-продукты выбор стоит между двумя группами стандартов — 19 и 34. И здесь все очень просто.
ГОСТ 34 — автоматизированные системы (АС).
ГОСТ 19 — программное обеспечение (ПО).
Как понять, что у вас система? В ней, помимо ПО, еще будет аппаратная часть, то есть будет что-то сказано про оборудование, которое входит в состав системы.
Важная ремарка. Всегда обращайте внимание на требования к оформлению документов — нумерация разделов, использование рамок, заполнение основных надписей. От ГОСТа к ГОСТу эти требования различаются.
В общем случае используется оформление по ГОСТ 2.105-19, но стандарты 19 и 34 серии имеют свои заморочки. Возможно, я наберусь сил и сделаю об этом отдельный пост.
См. также
Виды электронных документов
В широком смысле ЭД делятся на формализованные и неформализованные. Для этих определений важен тип (сила) электронной подписи, используемой для их подписания.
К первой категории относятся бумаги, которые направляются в ФНС, суд и другие государственные органы. Например, бухгалтерскую и налоговую отчетность допускается сдавать в электронном виде в установленных форматах при условии, что документированная информация подписана усиленной квалифицированной подписью.
Документы налогового учета, в отношении которых установлены специальные форматы и процедуры обмена, дополнительно требуют обязательного посредничества Оператора ЭДО!
Аналогично обстоят дела с обращениями в суд. Иски, ходатайства и другие файлы разрешено отправлять в электронном виде. При обращении в арбитражные суды подача электронных документов происходит через сервис «Мой арбитр». Для отправки документов в суды общей юрисдикции нужно создать личный кабинет на сайте ГАС «Правосудие» и воспользоваться вкладкой «Подача процессуальных документов в электронном виде». В обоих случаях заполняются необходимые формы, загружаются документы, которые подписываются усиленной квалифицированной подписью.
Другие государственные органы также предоставляют возможность вести документооборот в электронном виде. Подобное решение удобно хотя бы потому, что позволяет избежать стояния в очередях или ожидания своего номера по электронной записи, а также увеличивает скорость обработки информации.
Документы второй группы, которые используются в межкорпоративном документообороте, составляются в условно-произвольной форме, к таким бумагам относятся:
- Договоры;
- Контракты;
- Соглашения;
- Первичные учетные документы.
Так, частью 2 статьи 434 ГК РФ закреплена возможность заключать гражданско-правовые соглашения с использованием ЭД. При этом не уточняется, как именно должны быть составлены и оформлены документы. Из юридической практики известно, что электронные договора, контракты и соглашения составляются аналогично бумажным аналогам и содержат те же обязательные реквизиты, закрепленные ГК РФ, что и бумажные аналоги.
Что касается подписания таких документов, рекомендуется также использовать квалифицированную цифровую подпись. Этот вид ЭП автоматически придает документу юридическую силу бумажного оригинала. Если договор подписывают обе стороны, используйте специализированное ПО, которое позволяет ставить несколько подписей в одном документе, а еще надежнее – систему оператора электронного документооборота. Оператор не только проверяет в момент подписания действительность сертификата ЭД, но и позволяет вести документооборот, даже неформализованными документами, по четко установленным правилам.
Рис. 1 Электронная подпись
Отдельно отметим, что работу с «первичкой» в электронном виде регулирует и ст. 9 Федерального закона от 06.12.2011 № 402-ФЗ (действующая редакция от 28.11.2018) «О бухгалтерском учете» и ст. 169 НК РФ, где прописаны аспекта обмена первичными документами в таком формате.
Вести первоначальную документацию в электронном виде удобно. Например, по запросу контролирующих органов можно за секунды найти оригинал электронного документа и предоставить его в виде файла документа и файла подписи на электронном носителе, а запрашивающий орган также быстро сможет его проверить сертифицированными средствами.
Компьютерная вёрстка (англ. Desktop publishing — «настольное издательство», сокращённо DTP) — использование персонального компьютера и специального программного обеспечения для создания макета с целью последующей печати в типографии или на принтере.
Пользователь создаёт собственный макет страницы, который может содержать текст, рисунки, фотографии и другие иллюстративные элементы. В зависимости от требуемого количества и качества материалов печать может выполняться на принтере, ризографе или в специализированных типографиях.
Примерами программного обеспечения, специализирующегося на компьютерной вёрстке, являются программы QuarkXPress, Adobe InDesign, Scribus, Microsoft Publisher, Apple Pages.
Под термином компьютерная вёрстка понимают не только создание макета страницы (page layout) для книг и журналов. Этот термин также используется для создания макетов рекламных объявлений, упаковки, дизайна выставочных стендов и т. п.
Зачем проверять актуальность стандарта?
С актуальностью я столкнулась будучи еще зеленой. Надо мне было разработать пояснительную записку. Окей, гугл — пояснительная записка ГОСТ. Нахожу стандарт, все радостно расписываю, а потом открываю его на другом сайте и вижу это страшно слово: «Недействующий». Думаю, не стоит описывать степень моего негодования в тот момент, а то, боюсь, не обойтись без нецензурных высказываний.
Но, как известно, негативный опыт — это тоже опыт. Поэтому с тех пор я всегда проверяю актуальность, прежде чем брать стандарт за основу.
Ищете там свой стандарт и, затаив дыхание, открываете его. Вверху страницы будет строчка, которая либо вас очень обрадует, либо сильно разочарует.
Может быть и третий вариант:
Обычно это значит, что есть новый стандарт, нужно только его поискать. При поиске вводим обозначение стандарта без года принятия.
Например, если мы нашли ГОСТ 2.105-95, и он оказался недействующим, то в поисковой строке напишем «ГОСТ 2.105» и, хлопая в ладоши, найдем этот ГОСТ уже 19 года.
Частный случай
А что делать, если в ТЗ прописан список необходимых к изделию документов, да еще и прописано, по каким ГОСТам их надо делать, а эти ГОСТы успели устареть?
Конечно, это очень неожиданно и неприятно, но самый главный совет — не принимайте самостоятельных решений и идите к заказчику. Он подскажет. А если нет — делайте по ТЗ. Так больше вероятности защититься.
В общем и целом, если вы только начинаете свою работу с ГОСТом, я советую вам придерживаться следующего плана при разработке документации:
Выберите нужный ГОСТ (если нет указаний от заказчика)
Отдельно может понадобиться ГОСТ по оформлению (обычно в стандарте прописано как оформлять или дана ссылка на соответствующий ГОСТ)
Найдите и обязательно проверьте актуальность
Внимательно прочитайте весь стандарт
Сделайте заметки о наиболее важных пунктах (очень полезно, если эти заметки еще и сохранять — вместо того, чтобы заново читать стандарт, всегда сможете быстро освежить его в памяти)
При разработке документа держите стандарт/заметки перед глазами
Когда документ готов, перечитайте стандарт (по первости что-то можете упустить)
Надеюсь, что эта инфа будет полезна тем, кто только начинает свою работу с ГОСТом.
Привет! Меня зовут Даша Григорьева, я технический писатель в компании 65apps. Мы занимаемся разработкой сложных мобильных решений, и моя задача — подготовка технической документации по проектам. Очень часто роль технического писателя бывает недооцененной в компании (не у нас, конечно). Поэтому я хочу рассказать, зачем компании-разработчику нужен такой специалист, что такое технический проект, чем он отличается от ТЗ и почему это все необходимо для разработки мобильного приложения.
Общаясь с большим количеством компаний, я все еще встречаю твердое убеждение в том, что написание технического задания для разработки ПО — пустая трата времени и денег. Мы в 65apps считаем иначе. Поэтому приведу несколько аргументов в пользу технической документации и расскажу, кто и как ее пишет.
Техническая документация позволяет оценить стоимость разработки и согласовать функциональность будущей системы. При возникновении споров о стоимости и сроках разработки той или иной фичи она может стать определенной гарантией для заказчика. С другой стороны, если возникнет потребность в развитии приложения, документация облегчит процесс доработки и даст четкое понимание, возможно ли встроить новую функциональность в существующую систему.
Другой пример — государственные организации или организации, чья деятельность ограничивается или подчиняется законам и надзорным органам. Они обязаны осуществлять разработку ПО по всем правилам и с соблюдением всех стандартов. В таких проектах техническая документация, подготовленная по ГОСТам, — необходимое условие.
И разумеется, грамотно составленная и актуальная документация необходима для того, чтобы каждый участник в процессе разработки мог обращаться к документам, если возникают вопросы по конкретной задаче или по всей системе в целом.
Техническое задание и технический проект — два разных документа. Техническое задание отвечает на вопрос «что нужно сделать?», его составляет аналитик в самом начале проекта. Технический проект разрабатывает технический писатель. Этот документ создается после ТЗ и отвечает на вопрос «как нужно делать?».
Техническая документация
При создании программы, одного лишь кода, как правило, недостаточно. Должен быть предоставлен некоторый текст, описывающий различные аспекты того, что именно делает код. Такая документация часто включается непосредственно в исходный код или предоставляется вместе с ним.
Подобная документация имеет сильно выраженный технический характер и в основном используется для определения и описания API, структур данных и алгоритмов.
Часто при составлении технической документации используются автоматизированные средства — генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из специальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML.
Использование генераторов документации и документирующих комментариев многими программистами признаётся удобным средством, по различным причинам. В частности, при таком подходе документация является частью исходного кода, и одни и те же инструменты могут использоваться для сборки программы и одновременной сборки документации к ней. Это также упрощает поддержку документации в актуальном состоянии.
Кто пишет техническую документацию
Обычно разработкой ТЗ занимается аналитик. Именно он общается с заказчиком / заинтересованным лицом и выявляет у него требования. В сложных случаях к процессу можно привлечь менеджера проекта, разработчиков, тестировщиков и других специалистов. Чем сложнее проект — тем больше требований к документации. Серьезные заказчики из крупных корпораций и госсектора требуют составлять документацию в соответствии с ГОСТами, а это задача очень трудоемкая, требующая внимательности к деталям и постоянной вовлеченности в процесс. И это не только ТЗ, но и технический проект, полностью описывающий все используемые в разработке решения, подходы и методологии. На него также распространяются ГОСТы. Подготовкой такой документации должен заниматься специалист — технический писатель.
Для крупных проектов иметь в штате технического писателя просто необходимо. Разработка решений для крупных заказчиков может длиться год и более, это довольно долгий срок. За это время возникает достаточное количество изменений, провоцирующих обновление документации. Кроме того, любая долгосрочная разработка ПО предполагает развитие. В этом случае актуальная техническая документация позволит снизить риски, закладываемые в работу исполнителей.
Исключение может быть сделано для представителей госсектора. Таким организациям необязательно иметь в своем штате специалистов соответствующего профиля, так как при возникновении необходимости всегда можно обратиться к профессионалам, которые выполнят качественно свою работу.
Читайте также: