Документация для составления технической документации строительство

Содержание

Документация на программное обеспечение — это документы, сопровождающие некоторое программное обеспечение (ПО) — программу или программный продукт. Эти документы описывают то, как работает программа и/или то, как её использовать.

Документирование — это важная часть в разработке программного обеспечения, но часто ей уделяется недостаточно внимания.

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

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

Лекция № 11 ( ч.1) Организационно-технологическая документация в строительстве

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

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

Часто при составлении технической документации используются автоматизированные средства — генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из специальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML. Использование генераторов документации и документирующих комментариев многими программистами признаётся удобным средством, по различным причинам. В частности, при таком подходе документация является частью исходного кода, и одни и те же инструменты могут использоваться для сборки программы и одновременной сборки документации к ней. Это также упрощает поддержку документации в актуальном состоянии.

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

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

Состав проектной документации для строительства частного дома (Часть 1)

Обычно, пользовательская документация представляет собой руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет инструкции о том, что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение.

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

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

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

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

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

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

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

Прошло много лет, программирование происходит в среде совершенно новых технологий, многие программисты, работая в стиле drag-and-drop, могут годами не видеть текст своих программ. Это не значит, что исчезла необходимость в их документировании. Более того, вопросы о наличии хоть какой-то системы, регламентирующей эту сторону создания программных средств, продолжают задавать постоянно. Спрашивают и о том, есть ли обязательные для применения стандарты (особенно остро стоит этот вопрос, когда разработка выполняется по заказу государственной организации или предприятия). Интересуются и тем, где можно купить имеющиеся стандарты.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Документация по сопровождению программного средства (system documentation) описывает программное средство с точки зрения ее разработки.

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

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

Внешнее описание программного средства (Requirements document).
Описание архитектуры программного средства (description of the system architecture), включая внешнюю спецификацию каждой ее программы.
Для каждой программы программного средства — описание ее модульной структуры, включая внешнюю спецификацию каждого включенного в нее модуля.
Для каждого модуля — его спецификация и описание его строения (design description).
Тексты модулей на выбранном языке программирования (program source code listings).
Документы установления достоверности программного средства (validation documents), описывающие, как устанавливалась достоверность каждой программы программного средства и как информация об установлении достоверности связывалась с требованиями к программному средству.

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

Руководство по сопровождению программного средства (system maintenance guide), которое описывает известные проблемы вместе с программным средством, описывает, какие части системы являются аппаратно- и программно- зависимыми, и как развитие программного средства принято в расчет в его строении (конструкции).
Общая проблема сопровождения программного средства — обеспечить, чтобы все его представления шли в ногу (оставались согласованными), когда программное средство изменяется. Чтобы этому помочь, связи и зависимости между документами и их частями должны быть зафиксированы в базе данных управления конфигурацией.

Процесс управления конфигурацией является процессом применения административных и технических процедур на всем протяжении ЖЦ ПС для определения состояния (базовой линии) программных объектов в системе, управления их изменениями и выпуском.

Источник: technologiarpo.blogspot.com

Пишем техническую документацию: руководство для непрофессионала

Осенью 2016 года нам с коллегой поручили улучшить документацию и контент в моей бывшей компании. Мы потратили год на все виды документации: справочник по API, руководства, учебные пособия, сообщения в блогах. До этого я 5 лет писала доки, но официально не обучалась этому. Но и неопытной меня нельзя назвать: кроме документирования API для проектов и стартапа, я ещё преподавала Python Flask на семинарах во время учёбы на последних курсах в университете. Но сейчас выпала возможность сосредоточиться только на любимом деле: помогать специалистам всех уровней через техническую документацию.

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.

Как люди на самом деле читают документацию?

«Нация содрогается от большого фрагмента слитного текста», фото The Onion

Знаете это чувство, как на картинке? Так бывает. Может и не физически, но, скорее всего, люди содрогаются умственно. Меня постоянно мучала мысль, что люди не будут читать мои тексты, если я не оформлю их легко усваиваемым способом. Чёрт возьми, такое может произойти даже с этой статьёй.

В исследовании направления взгляда Neilson Norman Group в 2006 году 232 пользователя просмотрели тысячи веб-страниц. Оказалось, что пользователи обычно смотрят на страницы по F-шаблону:

«Сначала читают в горизонтальном направлении, как правило, в верхней части области с контентом. Это верхний элемент фигуры F».
«Затем немного перемещаются вниз по странице — и совершают второе горизонтальное движение, которое обычно охватывает более короткую область, чем предыдущее. Этот дополнительный элемент образует средний элемент фигуры F».
«Наконец, пользователи сканируют левую сторону контента по вертикали. Иногда это медленное и систематическое сканирование, которое отображается в виде сплошной полосы на теплокарте. Иногда движение более быстрое, образующее пятна на теплокарте. Это последний вертикальный элемент в фигуре F».

Теплокарты Nielsen Norman Group

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

Важно отметить, что F-шаблон мешает пользователям, но хорошее позиционирование контента помогает предотвратить F-сканирование.

Каковы конкретные последствия для документации?

В первых двух абзацах следует указать самую важную информацию
Критически важны первые 3−5 слов
Заголовки, абзацы и маркированные списки с информативными словами
Изменения шрифта (размер, ссылки, выделения жирным и т. д.) могут быть необходимы, чтобы удержать внимание читателя

Так как структурировать контент на странице?

Предотвратите сканирование: убедитесь в выделении информации, которая нужна читателю
Одна мысль на абзац. Если их несколько, разбейте абзац
Пользователи пропускают всё, что похоже на баннеры, поэтому будьте осторожны с иллюстрациями
Не расширяйте слишком сильно колонку с текстом: оптимально 65−90 символов

Кроме того, у абзацев есть своя специфика. Подобно слитному тексту The Onion, когда вы читаете много абзацев, можно пропустить суть. Тогда зачем использовать их так часто? Давайте проведём эксперимент из документации Keen IO:

Быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил: в названии должно быть не более 64 знаков. Оно должно содержать только символы ASCII. Оно не может быть значением null.

Теперь быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил:

В названии должно быть не более 64 знаков
Оно должно содержать только символы ASCII
Оно не может быть значением null

Позже мы подробнее обсудим вёрстку документации и навигацию по ней.

Примеры кода

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

Контекст в примере кода важен для успеха разработчика. Разработчики любят быстро копировать и вставлять. Вот пример с Keen IO API:

Разработчик быстро копирует и вставляет этот код. И…

Во-первых, как они вообще запускают файл? Вероятно, как node file_name.js , но этого нет в коде. Можно было бы указать в комментарии вверху.

Хорошо, они запустили его и… ReferenceError: Keen is not defined . 🙁 Клиент Keen не инициировался, в верхней части нет оператора import или require, и он работает только после установки библиотеки npm.

Пользователь всё починил и запустил ещё раз… Угадайте?! Ещё одна ошибка! your_project_id и your_write_key отсутствуют.

Всё это можно было бы сделать более очевидным.

Вот пример из документации Twilio, которая предоставляет хороший контекст для конечного пользователя:

Скриншот из документации библиотеки Twilio Node Helper

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

Копипаст багов

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

Кажется довольно безобидным, верно? Подумайте ещё раз, что происходит, когда вы копируете и вставляете это в командную строку? Вы, скорее всего, получите:

Распространённая ошибка. Либо вы хотите, чтобы команда выглядела как в командной строке, либо вы случайно её скопируете. Я бы рекомендовала отказаться от $ . Ещё можно найти способ запретить копипаст этого символа, чтобы ошибка не раздражала пользователей.

Более свежий пример: вы проверяли, насколько легко выделить код, который пользователь хочет скопировать?

Келси Хайтауэр изо всех сил пытался скопировать образец кода из StackOverflow на презентации Google Cloud Next.

«Хорошие программисты копируют, великие программисты вставляют»

Он сделал это намеренно? Мы никогда этого не узнаем. Тем не менее, это иллюстрация, как программисты пытаются выделить большие блоки текста на некоторых сайтах документации. Убедитесь, что пользовательский интерфейс сайта позволяет легко копировать большие блоки. Можно даже разбить эти блоки, чтобы объяснить фрагменты по отдельности.

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

«Вот и всё!»

«Вот и всё!» Фраза кажется довольно безобидной вне контекста, но представьте, как воспринимаются определённые слова вроде «легко», «просто», «тривиально» и «несложно», когда у вас проблемы — не здорово! Когда человек застрял, пытаясь заставить API работать, такая фраза подвергает сомнению его интеллект и заставляет задать вопрос: «Значит, я глупый?» Это деморализует.

Чрезмерное упрощение

Упрощение встречается повсеместно. Оно наиболее распространено среди новичков в написании документации. Зачастую авторы документации — одновременно и разработчики системы, поэтому некоторые вещи им кажутся «лёгкими». Но ведь они разработали эту функцию, написали для неё код, проверили много, много раз, а потом написали документацию.

Когда вы делаете что-то десятки раз, то ясное дело, что это будет «легко» для вас. Но как насчёт того, кто никогда раньше не видел UI или функцию?

Сопереживание

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

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

Попросите менее опытных участников проекта честно прокомментировать документацию
Поощряйте менее опытных участников проекта вносить свой вклад или указывать на пункты документации, которые они не понимают
Создайте окружение, где поощряются вопросы, в том числе такие, какие могут показаться «очевидными» для опытных участников проекта — это поможет заметить «слепые зоны»
В процессах код-ревью и CI используйте линтеры, чтобы гарантировать эмпатию и дружественность языка для всех пользователей
Наконец, попросите прокомментировать документацию реальных пользователей, покажите им текст и спросите, всё ли понятно

Сообщения об ошибках как вид документации

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

Кейт на сайте Write The Docs рассказывает много полезного о написании сообщений об ошибках. Многое я узнала во время прошлой работы над сообщениями об ошибках API, а также будучи на другой стороне баррикад, получая сообщения об ошибках других API в качестве разработчика.

Кейт говорит, что хорошие сообщения об ошибках построены на трёх принципах:

Скромность

Сразу нужно извиниться, даже если это не ваша вина. Это я практикую также в службе поддержки.

Извините, не удалось подключиться к ___. Пожалуйста, проверьте сетевые настройки, подключитесь к доступной сети и повторите попытку.

Гуманность

Используйте понятные человеку термины, избегайте фраз типа «исключение выброшено целевым объектом вызова». При написании кода, для которого вызывается много сообщений об ошибках, легко сбиться с понятной лексики.

Пример (ошибка кода состояния 401 у Twilio):

Полезность

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

Извините, изображение, которое вы пытались загрузить, слишком большое. Попробуйте снова с изображения меньше, чем 4000px по высоте и 4000px по ширине.

Как писать сообщения об ошибках

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

Сообщения об ошибках в документации

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

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

В случае ошибки 20003 (ошибка кода состояния 401, упомянутая ранее), есть много возможных причин, которые чётко изложены в каталоге.

Источник: https://www.twilio.com/docs/api/errors

Stripe делает нечто подобное с детальным описанием различных кодов ошибок.

Источник: https://www.twilio.com/docs/api/errors

Вы даже можете найти свои сообщения об ошибках в вопросах StackOverflow. Ответьте на них скромно, по-человечески и с пользой. Из-за SEO пользователи часто попадают с вашими сообщениями об ошибках на StackOverflow, а не в реальную документацию.

Подсказка: если кто-то не ответил скромно, по-человечески и с пользой, то с достаточной «репутацией» можно редактировать ответы StackOverflow.

Выбор слов

У многих слов есть устоявшиеся ментальные модели. Например, такие слова, как «библиотеки», SDK, «обёртки» и «клиенты» уже перегружены и проходят мимо внимания читателя.

В своей лекции «Даже для этой лекции трудно подобрать название» на Write The Docs Рути Бендор говорит, почему выбор правильных слов может быть таким трудным.

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

В такой ситуации как никогда справедлива известная поговорка: «Есть только две трудные задачи в области информатики: инвалидация кеша и придумывание названий». Цитату часто приписывают Филу Карлтону, но сегодня ходит много вариантов этой поговорки. Иногда в конце добавляют «… и ошибка на единицу». Рути считает это демонстрацией, что программное обеспечение в наши дни во многом основано на чужом коде или работе.

Почему же сохраняются плохие названия объектов (или документация)?

Как и с чрезмерным упрощением, мы часто не понимаем, что название плохое. Это то, что Рути называет сбоем эмпатии. Это как сказать, что проблема неудачных слов меня не касается, поэтому её не существует.

Мне это ещё напоминает то, что Рути называет ошибкой мышления новичка. Это как сказать «Мне это совершенно ясно. Не понимаю, как кто-то не может этого понять».

Наконец, Рути упоминает ошибку локализации. Например, слово Bing по-китайски означает «больной».

Почти 25% разработчиков читают и пишут по-английски не «очень хорошо». При общении в проекте используйте понятный и доступный язык для людей из неанглоязычных стран.

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

Подсказка: я твёрдо верю, что один из величайших «трюков» для решения этих проблем — разнообразие команды, работающей над документацией.

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

Привязаны к ней
Не находим времени
Не видим важности
У нас нет агентства, чтобы её исправить

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

Как правильно подобрать слова?

Для начала рекомендую задать вопрос: какие слова используют ваши пользователи? В разных программистских кругах в ходу разные термины, не пытайтесь использовать другие. Это полезно не только для читателей, но также для поиска и SEO.

В конце концов, всё неизбежно сводится к субъективной оценке. Однако есть несколько принципов, которые стоит учесть. Рути говорит, что плохие названия — это те, что могут:

смутить
огорчить
ввести в заблуждение
запутать
оскорбить

способствуют внезапному прояснению («вот оно что!»)
вводят в контекст
объясняют
освещают
оказывают поддержку

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

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

Источник: habr.com

ГОСТ 2.103-2013 Единая система конструкторской документации. Стадии разработки

Текст ГОСТ 2.103-2013 Единая система конструкторской документации. Стадии разработки

Единая система конструкторской документации

Unified system for design documentation Stages of designing

____________________________________________________________________
Текст Сравнения ГОСТ 2.103-2013 с ГОСТ 2.103-68 см. по ссылке.
— .
____________________________________________________________________

МКС 01.110
ОКСТУ 0002

Дата введения 2015-07-01

Предисловие

Цели, основные принципы и основной порядок проведения работ по межгосударственной стандартизации установлены в ГОСТ 1.0-2015 «Межгосударственная система стандартизации. Основные положения» и ГОСТ 1.2-2015 «Межгосударственная система стандартизации. Стандарты межгосударственные, правила и рекомендации по межгосударственной стандартизации. Правила разработки, принятия, обновления и отмены»

Сведения о стандарте

1 РАЗРАБОТАН Федеральным государственным унитарным предприятием «Всероссийский научно-исследовательский институт стандартизации и сертификации в машиностроении» (ВНИИНМАШ), Автономной некоммерческой организацией Научно-исследовательский центр CALS-технологий «Прикладная логистика» (АНО НИЦ CALS-технологий «Прикладная логистика»)

2 ВНЕСЕН Федеральным агентством по техническому регулированию и метрологии

3 ПРИНЯТ Межгосударственным советом по стандартизации, метрологии и сертификации (протокол от 14 ноября 2013 г. N 44, приложение N 24 доп.)

За принятие проголосовали:

Краткое наименование страны по МК (ИСО 3166) 004-97

Код страны по
МК (ИСО 3166) 004-97

Сокращенное наименование национального органа по стандартизации

Минэкономики Республики Армения

Госстандарт Республики Беларусь

Госстандарт Республики Казахстан

4 Приказом Федерального агентства по техническому регулированию и метрологии от 26 ноября 2014 г. N 1794-ст межгосударственный стандарт ГОСТ 2.103-2013 введен в действие в качестве национального стандарта Российской Федерации с 01 июля 2015 г.

5 ВЗАМЕН ГОСТ 2.103-68

6 ИЗДАНИЕ с поправкой (ИУС 7 2015 г.), с поправкой (ИУС 10 2016 г.). Декабрь 2018 г.

Информация об изменениях к настоящему стандарту публикуется в ежегодном информационном указателе «Национальные стандарты», а текст изменений и поправок — в ежемесячном информационном указателе «Национальные стандарты». В случае пересмотра (замены) или отмены настоящего стандарта соответствующее уведомление будет опубликовано в ежемесячном информационном указателе «Национальные стандарты». Соответствующая информация, уведомление и тексты размещаются также в информационной системе общего пользования — на официальном сайте Федерального агентства по техническому регулированию и метрологии в сети Интернет (www.gost.ru)

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

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

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

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

В настоящем стандарте использованы нормативные ссылки на следующие межгосударственные стандарты:

ГОСТ 2.002-72 Единая система конструкторской документации. Требования к моделям, макетам и темплетам, применяемым при проектировании

ГОСТ 2.052-2015 Единая система конструкторской документации. Электронная модель изделия. Общие положения

ГОСТ 2.053-2013 Единая система конструкторской документации. Электронная структура изделия. Общие положения

ГОСТ 2.102-2013 Единая система конструкторской документации. Виды и комплектность конструкторских документов

ГОСТ 2.118-2013 Единая система конструкторской документации. Техническое предложение

ГОСТ 2.119-2013 Единая система конструкторской документации. Эскизный проект

ГОСТ 2.120-2013 Единая система конструкторской документации. Технический проект

ГОСТ 2.125-2008 Единая система конструкторской документации. Правила выполнения эскизных конструкторских документов. Общие положения

ГОСТ 2.601-2013 Единая система конструкторской документации. Эксплуатационные документы

ГОСТ 2.602-2013 Единая система конструкторской документации. Ремонтные документы

Примечание — При пользовании настоящим стандартом целесообразно проверить действие ссылочных стандартов в информационной системе общего пользования — на официальном сайте Федерального агентства по техническому регулированию и метрологии в сети Интернет или по ежегодному информационному указателю «Национальные стандарты», который опубликован по состоянию на 1 января текущего года, и по выпускам ежемесячного информационного указателя «Национальные стандарты» за текущий год. Если ссылочный стандарт заменен (изменен), то при пользовании настоящим стандартом следует руководствоваться заменяющим (измененным) стандартом. Если ссылочный стандарт отменен без замены, то положение, в котором дана ссылка на него, применяется в части, не затрагивающей эту ссылку.

3 Термины, определения и сокращения

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

В настоящем стандарте применены следующие термины с соответствующими определениями:

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

[ГОСТ 14.004-83, пункт 20]

3.1.2 литера: Реквизит конструкторского документа (комплекта конструкторских документов) на изделие, соответствующий стадии его разработки.

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

[ГОСТ 16504-81, ст.8]

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

3.1.5 проектная конструкторская документация: Конструкторская документация, выполненная на стадиях технического предложения, эскизного и технического проектов.

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

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

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

формат данных: Порядок расположения символов данных, позволяющий распознавать их составные части.

Примечание — Формат данных приобретает изменение в зависимости от конкретной совокупности символов данных, например, формат сообщения данных.

[ГОСТ 17657-79, приложение, пункт 11]

3.2 Сокращения

В настоящем стандарте приняты следующие сокращения:

КД — конструкторские документы (документы, документация);

ТЗ — техническое задание.

4 Основные положения

4.1 Стадии разработки КД могут выполняться в виде разработки проектной и рабочей КД. Стадии разработки КД и этапы выполнения работ, устанавливаемые настоящим стандартом, приведены в таблице 1.

Этапы выполнения работ

Разработка проектной КД

Разработка технического предложения

Разработка эскизного проекта

Изготовление и испытание и/или разработка и анализ материальных макетов (при необходимости) и (или) разработка, анализ электронных макетов (при необходимости)

Рассмотрение и утверждение КД эскизного проекта с присвоением документам литеры «Э»

Разработка технического проекта

Изготовление и испытание материальных макетов (при необходимости) и/или разработка, анализ электронных макетов (при необходимости)

Рассмотрение и утверждение КД технического проекта с присвоением КД литеры «Т»

Разработка рабочей КД

Разработка КД опытного образца (опытной партии) изделия

Разработка КД, предназначенной для изготовления и испытания опытного образца (опытной партии) изделия, без присвоения литеры

Изготовление и предварительные испытания опытного образца (опытной партии) изделия

Корректировка КД по результатам изготовления и предварительных испытаний опытного образца (опытной партии) изделия с присвоением КД литеры «О»

Приемочные испытания опытного образца (опытной партии) изделия

Корректировка КД по результатам приемочных испытаний опытного образца (опытной партии) изделия с присвоением КД литеры «

При необходимости — повторное изготовление и испытания опытного образца (опытной партии) по документации с литерой «»

Разработка КД на изделие серийного (массового) производства

Изготовление и испытание установочной серии по документации с литерой «»)

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

Для изделия, разрабатываемого по заказу Министерства обороны, при необходимости, — изготовление и испытание головной (контрольной) серии по КД с литерой «А» и соответствующая корректировка КД с присвоением им литеры «Б»

Разработка КД на изделие единичного производства

Разработка КД, предназначенной для изготовления и испытания изделия с присвоением им литеры «И»

Примечание — Всем стадиям разработки рабочей КД могут предшествовать стадии разработки проектной КД.

__________
* Текст документа соответствует оригиналу. — .

4.2 Номенклатура видов документов, разрабатываемых на каждой стадии разработки КД — по ГОСТ 2.102, если состав документации не установлен в ТЗ на разработку.

4.3 Обязательность выполнения стадий разработки и этапов выполнения работ, форму представления КД (бумажная и (или) электронная) должен устанавливать разработчик, если это не установлено в ТЗ на разработку.

4.4 При невыполнении одной из стадий разработки, присущих опытно-конструкторской работы, работы, относящиеся к этим стадиям, должны быть осуществлены на одной из выполняемых стадий разработки.

4.5 Требования к выполнению КД должны соответствовать требованиям Единой системы конструкторской документации.

4.6 Необходимость разработки макетов, их вид, условия и программы испытаний (анализа), а также необходимость разработки документации для изготовления и испытания макетов должен устанавливать разработчик, если это не установлено в ТЗ на разработку. Макеты могут выполняться в материальной форме (материальный макет) или виртуальной форме (электронный макет). Требования к материальному макету по ГОСТ 2.002, к электронному макету — по ГОСТ 2.052.

Материальные макеты следует изготавливать, как правило, по эскизным КД, в соответствии с ГОСТ 2.125*

4.7 При выполнении электронных КД требования к форматам данных рекомендуется устанавливать на предшествующей стадии разработки, если это не установлено ТЗ.

4.8 При выполнении электронных КД электронная структура изделия и электронная модель изделия (сборочной единицы, комплекса, комплекта) следует выполнять со степенью детализации, соответствующей стадии разработки. Требования к электронной модели изделия — по ГОСТ 2.052, к электронной структуре изделия — по ГОСТ 2.053.

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

4.10 Техническое предложение — совокупность проектных КД, которые должны содержать технические и технико-экономические обоснования целесообразности разработки документации изделия на основании анализа ТЗ и различных вариантов возможных решений изделий, сравнительной оценки решений с учетом конструктивных и эксплуатационных особенностей разрабатываемого и существующих изделий, а также патентные исследования.

Техническое предложение после согласования и утверждения в установленном порядке является основанием для разработки эскизного (технического) проекта.

Перечень работ — по ГОСТ 2.118.

4.11 Эскизный проект — совокупность проектных КД, которые должны содержать принципиальные конструктивные решения, дающие общее представление о назначении, об устройстве, принципе работы и габаритных размерах разрабатываемого изделия, а также данные, определяющие его основные параметры.

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

Перечень работ — по ГОСТ 2.119.

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

Технический проект после согласования и утверждения в установленном порядке служит основанием для разработки рабочей КД.

Перечень работ — по ГОСТ 2.120.

4.13 Ранее разработанные КД следует применять при разработке новых или модернизации изготовляемых изделий в следующих случаях:

а) в проектной КД (техническом предложении, эскизном и технических проектах);

б) в рабочей КД с литерами «»), «А», «Б» и «И», если литерность применяемого документа та же или более высокая.

Литерность полного комплекта КД определяется низшей из литер, указанных в КД, входящих в комплект, кроме КД покупных изделий.

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

4.15 На стадиях разработки «Разработка проектной КД» следует разрабатывать на проектную КД*.
__________
* Текст документа соответствует оригиналу. — .

На стадиях «Разработка рабочей КД» следует разрабатывать рабочую КД.

Рабочая КД, передаваемая (поставляемая) организации-изготовителя для производства изделий включает, в том числе, эксплуатационную документацию, выполненную по ГОСТ 2.601, которая затем поставляется потребителю (эксплуатанту) вместе с изделием. Проектную и рабочую КД следует разрабатывать на стадии жизненного цикла изделия «Проектирование (разработка)».

Ремонтную КД, в случае необходимости, следует разрабатывать по ГОСТ 2.602 на стадии жизненного цикла изделия «Ремонт», как правило, после определенного срока эксплуатации изделия*.

Приложение А (справочное). Комментарии к пунктам стандарта

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

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

Материальный и электронный макеты следует разрабатывать:

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

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

в) на стадии разработки технического проекта с целью проверки основных конструктивных решений разрабатываемого изделия или его составных частей по пространственно-кинематическому взаимодействию с другими изделиями и составных частей между собой и условий эргономичности;

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

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

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

Электронный текст документа
и сверен по:
официальное издание
М.: Стандартинформ, 2019

Источник: allgosts.ru