3.6.1 Поиск путей повышения качества выпускаемой технической документации (F/01.7) - трудовая функция, присвоенная профессиональным стандартом гражданам, квалификация которых позволяет занимать должности программиста, занятого программированием, и (или) инженера, профессионально занимающегося инженерным делом в части документирования. Более того, требуется практический опыт работы программистом или опыт программирования для собственных нужд (научных, личных или иных), опыт участия в разработке и сопровождении крупных комплектов технической документации в качестве технического писателя. Редакция от 28.10.2020.
3.6.1 Поиск путей повышения качества выпускаемой технической документации (F/01.7)
Смотрите: |
Создан 20.10.2020 15:40:55
Путь к свету.
Трудовые действия
Поиск и изучение лучших образцов технической документации
Поиск и изучение лучших образцов технической документации - поиск как ключевое слово.
Поиск - это Перебор определенной совокупности объектов, при котором проводится анализ каждого объекта до тех пор, пока не будет исчерпана совокупность объектов или анализ не покажет, что объект удовлетворяет определенным критериям. Примечание - Результатом поиска могут быть сведения о наличии или отсутствии объекта в совокупности, в которой произведен поиск, сам искомый объект или сведения о его расположении, обеспечивающие последующие манипуляции с объектом, например чтение данных по адресу [из п. 3 прил. ГОСТ 20886-85].
Образец-эталон - это Образец продукции, утвержденный в установленном порядке и предназначенный для сравнения с ним изготовленной продукции при ее приемке и поставке. Образец-эталон продукции является частным случаем контрольного образца и представляет собой реальный экземпляр выпускаемой продукции, применяемый в качестве дополнения к технической документации при невозможности установления в ней всех требований, характеризующих, как правило, внешний вид этой продукции [из п. 1.3.9 Р 50-605-80-93].
Вероятно, образец-эталон и должен послужить лучшим образцом технической документации. Теперь о критериях.
Критерии (criteria) - это Стандарты, правила, либо тесты, на которых основано определенное суждение либо решение, или с помощью которых можно оценить продукт, услугу, результат либо процесс [из п. 3.2.36 ГОСТ Р 57306-2016].
Логика и здравый смысл подсказывают, что лучшие образцы технической документации должны соответствовать стандартам и правилам, с помощью которых можно оценить их «лучшесть». Стандарты и правила общеизвестны, поэтому разработка технической документации уровня образца-эталона не составит большого труда. Тогда зачем заниматься поиском лучших образцов?
Все дело, конечно, в лени. Казалось бы, значительно проще поиметь «рыбу» любого технического документа и подготовить свой на его основе, но подтверждение соответствия «рыбы» образцу-эталону тоже потребует определенных трудозатрат. Отсюда выводы:
- искать надо не «рыбу»;
- искать надо методики разработки;
- в качестве «рыб» использовать только утвержденные на самом высоком уровне документы.
Полуфабрикаты - филе и стейки без хвостов и чешуи - можно заимствовать здесь, методики (более полусотни по ГОСТ 34.хуз) - здесь, а про концептуальные документы можно посмотреть здесь.
Изучение практики документирования на других предприятиях и в других организациях
Изучение практики документирования на других предприятиях и в других организациях - занятие интересное. Но почти невероятно, что некое предприятие или какая иная организация близко подпустит стороннего интересанта к своей наилучшей доступной технологии или наилучшей добросовестной практике. Но не потому, что там все такое наилучшее, а потому, что почти везде одно и то же болото. Убедиться в этом легко, достаточно устроиться в любое заведение хотя бы на время прохождения испытательного срока, стать инсайдером. «Просите - и получите, ищите - и найдете, стучите - и вам откроют».
НО! «Берегитесь лжепророков. Они приходят к вам в овечьих шкурах, внутри же они - хищные волки. Их вы узнаете по их плодам».
В наилучшем случае все сводится к тому, что в заведении имеется небольшое писательское подразделение, которое в самые сжатые сроки переписывает все то, что «наваяли» прочие участники проектной команды, задействованные на предыдущих стадиях и (или) этапах проекта. Примерно так, как расписано здесь.
А на словах у всех все очень гладко, чинно и благопристойно. Один гендир колотил себя кулаком в грудь, доказывая, что у него на четвертом этаже сто человек сидят и пишут, и пишут, и пишут... На поверку вышло, что в конторе ВСЕГО 22 сотрудника в трех комнатухах на третьем этаже.
Участие в профильных выставках, семинарах, конференциях
Участие в профильных выставках, семинарах, конференциях - а пуркуа бы да не па? Всегда интересно потусоваться в кругу «социально близких», попить кофейку с сетевыми соратниками. Вполне приятное трудовое действие. Да и интересную информацию всегда можно почерпнуть. Набрать полный пакет буклетов, чтобы внимательнее просмотреть их дома. После чего 90 % полиграфической продукции переместить в мусоропровод.
Или выступить на семинаре по заявленной или запланированной теме. Тоже неплохо - не только мир посмотреть, но и себя показать. Вот небольшое лирическое отступление - какой же это был драйв!
Проведение семинаров по техническому документированию
Исходя из озвученного выше, от идеи организации и проведения собственных семинаров для технических писателей или участия в них на других площадках мы отказались, изучив имеющийся опыт и убедившись в том, что подобные мероприятия проводятся все больше для расширения круга знакомств и не приносят особой пользы неподготовленным слушателям, а «лекторам» - чувства глубокого удовлетворения 
Действительно, интересен ли техписам семинар на тему «Документирование НИР и ОКР: разработка ТЗ, этапы выполнения, оформление результатов. Для главных инженеров, конструкторов, руководителей проектов, ответственных исполнителей НИР и ОКР»?
Семинар на указанную тему был проведен с нашим участием в Санкт-Петербурге 20.12.2012 г. Следует отметить, что подготовка семинара его организаторами велась очень тщательно в течение полугода, аудиторию порядка тридцати человек составляли преимущественно представители военно-промышленного комплекса, от «простого советского» до «непростого» главного инженера.
Основные вопросы семинара:
- Разработка, согласование и утверждение ТЗ на НИР и ОКР:
- Разработка технического задания (ТЗ) на проведение научно-исследовательской работы (НИР) и порядок выполнение НИР в соответствии с ГОСТ 15.101-98 «СРПП. Порядок выполнения научно-исследовательских работ».
- Разработка ТЗ на выполнение опытно-конструкторской работы (ОКР) и порядок выполнения в соответствии с ГОСТ Р 15.201-2000 «СРПП. Продукция производственно-технического назначения. Порядок разработки и постановки продукции на производство».
- Особенности оформления ТЗ на НИР и ОКР в соответствии с действующими требованиями.
- Порядок согласования и утверждения ТЗ на НИР и ОКР.
- Требования к технико-экономическому обоснованию как приложению к ТЗ.
- Порядок согласования и утверждения ТЭО на НИР и ОКР.
- Проблемные вопросы на этапах разработки и согласования ТЗ.
- Этапы выполнения НИР, ОКР. Отчетные документы. Документальное оформление ОКР на этапах:
- эскизного проектирования;
- технического проектирования;
- разработки рабочей конструкторской документации (РКД) на опытный образец;
- изготовления опытных образцов;
- испытания опытных образцов (предварительных и приемочных) в соответствии с ГОСТ 15.309–98 «СРПП. Испытания и приемка выпускаемой продукции. Основные положения»;
- корректировки РКД по результатам испытаний и присвоение КД литеры «О1».
- Оформление результатов НИР и ОКР как обязательной части документации на продукцию, содержащую инновационные разработки. Комплектность технической документации. Оформление результатов интеллектуальной деятельности.
- Предъявление работ по этапам НИР, ОКР в соответствии с ГОСТ 15.309–98 Заказчику, представителю заказчика. Пояснение по последним директивам Министерства обороны военным представительствам на предприятиях.
Как организаторы ни старались, но программа восьмичасового семинара все равно оказалась поломанной, поскольку в последний момент был приглашен преподаватель Санкт-Петербургского университета ГПС МЧС России, оказавшийся очень даже «в теме». В итоге семинар превратился в jam session, содокладчики разыграли «блюз в четыре руки», вышли за рамки тематики, затем присоединились и слушатели. Среди них оказались и выпускники военных академий, многие знали преподавателя лично, а «Техническую документацию» - заочно, включая сетевое общение. В итоге восемь часов прошли «на ура», в теплой дружественной обстановке. Спасибо организаторам!
Изучение современных методов и средств разработки технической документации
Изучение современных методов и средств разработки технической документации - однозначности ради обратимся к терминологии.
Метод - это Инструментальный способ, прием достижения какой-либо цели или решения конкретной задачи. Примечания:
- Прием или система (совокупность) приемов практического или теоретического освоения (познания) действительности.
- Инструкция для пошагового достижения определенной цели.
- Комплексный подход к организации деятельности во взаимосвязи целей, исполнителей, ресурсов, оборудования и технологий.
[из п. 3.7 ГОСТ Р 54097-2010].
Средство (инструментальное) - это Компьютерная программа, используемая как средство разработки, тестирования, анализа, производства или модификации других программ или документов на них [из п. 3.5 ГОСТ Р 56939-2016]. Ключевое словосочетание - «или документов на них».
Инструментальных способов разработки техдокументации не так уж и много. Как в строительстве: можно собирать муравейники из хвойных иголочек, пирамиды из блоков, строить хрущевки из панелей или кирпича, а человейники - из монолитного бетона. Можно писать отдельными буковками, словами, фразами и даже элементарными предложениями, достигая немыслимых «синтаксических вершин». Но можно подойти к процессу творчески - почти ничего не писать.
Автор склонен к реюзингу - многократному и повторному использованию одних и тех же фрагментов текста и медийного контента. Повторяться лень, любопытные могут просмотреть раздел Автоматизация разработки технической документации, в котором имеется масса полезной информации.
Но есть и ранее нигде не упомянутая «фишечка»: когда фрагменты текста многократно и повторно «обкатываются» в различных документах, как морские голыши прибоем, текст становится настолько универсален, что впору менять местами целые абзацы и даже параграфы. Общий смысл итогового текста не меняется, но достигается идеальное сопряжение сопрягаемых поверхностей между собой и иным смежным текстом.
Средства разработки? Тут каждому свое: для индивидуального «творчества» автор предпочитает AuthorIT, для командной работы (по скромному мнению автора) в настоящее время наиболее удобна связка Jira+Atlassian Confluence. Но в идеале, конечно, Docuvera.
Чуть-чуть о Docuvera
Docuvera совсем недавно обнаружена на сайте AuthorIT Software Corporation Ltd. в ходе поиска свежей информации об AuthorIT. Поисковые машины выдают крайне мало информации о Docuvera, клип же становится безумно интересным с момента 1:26 мин просмотра. Обратной связи - как сделать buy, purchase или acquire - автор не нашел, но подписался на рассылку (мало ли чего любопытного всплывет).
Показано, как выполняется связь и внедрение объектов (топиков) из одного проекта в другой (путем перетаскивания), именно данная возможность и является ключевой во всей авторской затее - применении Atlassian Confluence при разработке технической документации.
Оценка качества создаваемой в компании технической документации
Оценка качества создаваемой в компании технической документации - в далеком-далеком 2011 году время автором был подготовлен и опубликован целый цикл статей, посвященных качеству технической документации, - О качестве...
Там и про оценку качества создаваемой в компании технической документации все расписано в деталях, вплоть до количественных и качественных оценочных элементов каждого фактора.
Разработка предложений по улучшению выпускаемой технической документации
Разработка предложений по улучшению выпускаемой технической документации - какие улучшения возможны вообще?
Постоянное улучшение (continual improvement) - Повторяющаяся деятельность по улучшению показателей деятельности [из п. 3.3.3 ГОСТ Р ИСО 37100-2018], а еще Повторяющаяся деятельность по увеличению способности выполнить требования. Примечание - Процесс установления целей и поиска возможностей улучшения является постоянным процессом, использующим наблюдения аудита и заключения по результатам аудита, анализ данных, анализ со стороны руководства или другие средства и обычно ведущим к корректирующим действиям или предупреждающим действиям [из п. 3.2.13 ГОСТ ISO 9000-2011].
Улучшение качества (quality improvement) - Часть менеджмента качества, направленная на увеличение способности выполнить требования к качеству. Примечание - Требования могут относиться к любым аспектам, таким как результативность, эффективность или прослеживаемость [из п. 3.3.20 ГОСТ Р 50646-2012].
Так как-то. Можно разрабатывать, а можно предложить и хорошо подзабытое старое, например Улучшение навигации в бумажных документах с применением AuthorIT.
Правда, статья эта в чистом виде «оформительская», причем многие заявленные в ней улучшения могут встретить «активное сопротивление» со стороны нормоконтроля, к примеру, вот такие «новшества»:
Дополнительная навигация внутри разделов-подразделов явно не помешает, это же крупные рубрики, большие по объему, но ГОСТ (Р) 2.105 это не предусмотрено. Дополнительная навигация, «не запрещенная циркулярно, но и не разрешенная вполне». Но спорить с нормоконтролерами себе дороже, а потому «и так сойдет»!
В целом же Разработка предложений по улучшению выпускаемой технической документации открывает широчайшие творческие горизонты, особенно при многопользовательской разработке и выпуске технической документации.
Оценка качества документирования на предприятии или в организации
Оценка качества документирования на предприятии или в организации - об этом двумя подразделами выше.
Разработка предложений по развитию процессов документирования на предприятии или в организации
Разработка предложений по развитию процессов документирования на предприятии или в организации - у автора такое предложение разработано и обкатано в реальных условиях эксплуатации: процессы следует не развивать, а сворачивать, сокращать их число. Чем меньше процессов, тем меньше организационных проблем, возникающих в ходе выполнения проекта его участниками, смотрите картинку по ссылке.
Необходимые умения
Исследовать программные средства на тестовом стенде
Исследовать программные средства на тестовом стенде весьма любопытно. Только с тестовым стендом, исследованиями и их направлением следует определиться предельно точно.
Если под тестовым стендом понимать Средство испытаний (Test means) как Техническое устройство, вещество и (или) материал для проведения испытаний [из п. 16 ГОСТ 16504-81], то это одно дело, а если проводить Стендовые испытания (Bench test) - Испытания объекта, проводимые на испытательном оборудовании [из п. 54 ГОСТ 16504-81], то совсем другое. Испытательное оборудование необходимо аттестовывать, равно как и персонал, участвующий в испытаниях. А это лишняя головная боль.
Исследования в общепринятом смысле часто определяют как процесс изучения какого-либо объекта и получения новых знаний, в технике же имеют место Исследовательские испытания (Investigation test) как Испытания, проводимые для изучения определенных характеристик свойств объекта [из п. 35 ГОСТ 16504-81]
Необходимо четко сформулировать понятия, рамки такого умения и конкретизировать свойства, подлежащие изучению (исследованию). На тестовом стенде (а что это?) можно провести статический анализ исходного кода программы, можно динамический, можно фаззинг-тестирование, а можно и просто под отладчиком программу погонять, если обозвать дебаггер тестовым стендом. Только специалист по всяческим уязвимостям - это редкая и довольно дорогая птица ручной работы, а пользоваться дебаггером способен любой юный пионерий. При этом каждый из них имеет опыт программирования для собственных нужд (научных, личных или иных).
Анализировать техническую документацию, извлекать из нее сведения, необходимые для решения поставленной задачи
Анализировать техническую документацию, извлекать из нее сведения, необходимые для решения поставленной задачи, тоже можно различными способами. Есть ГОСТ Р 7.0.99-2018 Система стандартов по информации, библиотечному и издательскому делу. Реферат и аннотация. Общие требования, в котором отлично расписано, как проводить такой анализ, т.е. реферирование и аннотирование, но в большей степени реферирование.
Суть затеи состоит в том, чтобы не озадачиваться прочтением документации целиком, поскольку своего рода «коэффициент шума» применительно к сведениям часто зашкаливает, слишком уж много информационного мусора вокруг нас. Реализуется же затея применением синтаксических анализаторов.
Как-то возникла необходимость «расчехвостить» некий военный стандарт, извлечь из его зверски запутанного текста структуру декомпозиции работ. Анализатор предсказуемо выдал (в различных словоформах) свыше четырехсот задач разработки, согласования и утверждения. И даже рассмотрения, но не предварительного. При этом ожидаемого равного количества задач разработки, рассмотрения, согласования и утверждения не обнаружилось, даже странно...
Собирать, анализировать и систематизировать доступную информацию
Собирать, анализировать и систематизировать доступную информацию - да можно и недоступную. Преступным путем.
Сбор информации - Прием, сохранение и хранение информации [из п. 66 ГОСТ Р 56602-2015].
Анализ (review) - Деятельность, предпринимаемая для установления пригодности, адекватности и результативности рассматриваемого объекта для достижения установленных целей. Примечание - Анализ может также включать определение эффективности. Пример - Анализ со стороны руководства, анализ проектирования и разработки, анализ требований потребителей, анализ несоответствий [из п. 3.8.7 ГОСТ ISO 9000-2011].
Анализ информации - Процесс исследования информации с целью извлечения полезной информации и принятия решений [из п. 3.5 ГОСТ Р 56571-2015].
Систематизация - Деятельность, заключающаяся в научно-обоснованной классификации и ранжировании совокупности конкретных объектов [из п. А.18 ГОСТ 1.1-2002].
Совершенно прозрачное и понятное умение.
Осваивать языки программирования
Осваивать языки программирования следует начинать с пеленок, в крайнем случае - со школьной скамьи. Так, собственно, и происходило с теми, кто в рамках школьного производственного обучения не записался на водительские курсы. Вопрос в том, к чему приложить полученные знания. И с какой целью.
Надо ли, к примеру, всерьез осваивать кроссплатформенный фреймворк Qt или достаточно простого умения читать и понимать коды? Но с языком преобразований XSLT уж точно необходимо быть близко знакомым.
Составлять и отлаживать несложные программы и тестовые примеры
Составлять и отлаживать несложные программы и тестовые примеры - это классика жанра...
Простые и сложные метеоусловия, к примеру, четко регламентированы статьями 80 и 81 документа «Наставление по производству полетов авиации вооруженных сил СССР НПП-78». А как классифицировать программы и тестовые примеры?
Можно предположить, что
#include <iostream>
#include <cstdlib> // для system
using namespace std;
int main()
{
cout << "Hello, world!" << endl;
system("pause"); // для MS Visual Studio
return 0;
}
несложная программа. А как же тогда «Это и я так могу... А чё ж сыграть-то? «Мурку!»».
Автор «составил» и отладил совсем, казалось бы, простенькую программу, смотрите ТЕКСТ ПРОГРАММЫ ГОСТ 19.401-78, но только ПРОГРАММА И МЕТОДИКА ИСПЫТАНИЙ ГОСТ 19.301-79 на нее получилась объемом в 28 листов формата А4. Почти все программные документы на нее по объему приближаются к тремстам листам. Так сложная программа или нет?
Любопытные могут пощелкать по пиктограммам 
,
,
,
,
,
, расположенным под заголовком данной статьи для понимания функциональности программки.
Подготавливать слайд-шоу и раздаточные материалы
Подготавливать слайд-шоу и раздаточные материалы - это отдельное и низкоуровневое дублирующееся «умение», ссылка будет позже.
Подготавливать технические статьи
Подготавливать технические статьи - какие конкретно?
Статья (article, paper) - Составная часть основного текста сборника, которая представляет собой законченное произведение, освещающее какую-либо тему. Примечания:
- По целевому назначению различаются научная, научно-популярная, массово-политическая, производственно-практическая статьи.
- Статья может быть также составной частью аппарата издания.
[из пп. 3.1.3.14 ГОСТ Р 7.0.3-2006]
Справочная статья - Структурная единица справочника, представляющая собой краткий ответ на вопрос, содержащийся в заголовке [из пп. 3.1.3.18 ГОСТ Р 7.0.3-2006]
Сопроводительная статья - Составная часть аппарата издания, в которой дается характеристика содержания произведения(ий) и (или) его автора(ов). Примечание - Сопроводительные статьи различаются по жанрам в зависимости от вида издания [из пп. 3.1.4.1 ГОСТ Р 7.0.3-2006]
Словарная статья - Структурная единица словаря/энциклопедии, представляющая собой относительно самостоятельный текст, включающая заглавное слово в виде словосочетания, выражения, понятия, термина и его пояснения, определения, толкования, эквиваленты на других языках и другие сведения [из пп. 3.1.3.17 ГОСТ Р 7.0.3-2006]
Статьи все технические, если не они гуманитарные, естественные и не представляющие собой литературно-художественные произведения.
Всегда можно подготовить статью в рамках какой-либо терминосистемы, предметной области или предметной области деятельности. Вопрос в присущем качестве и потребительских свойствах результирующей статьи, а они напрямую зависят от компетентности автора в рассматриваемых вопросах.
Создавать демонстрационные или обучающие ролики
Создавать демонстрационные или обучающие ролики - тоже отдельное и низкоуровневое дублирующееся «умение», ссылка будет позже.
Подготавливать выступления и выступать публично
Подготавливать выступления и выступать публично - не всем дано, если речь о публичных выступлениях. Хоть как-то подготовиться к выступлению сможет каждый, если будет следовать известной связке, после чего более-менее внятно что-то промямлит на публике. Но это наихудший вариант, разумеется.
Лучший вариант - это сочный, отлично поставленный баритон, плюс следование вышеупомянутой связке при подготовке, а не дешевым приемам риторики и желанием что-то впарить. Да и рассчитывать следует на заинтересованную аудиторию, которую предварительно неплохо и изучить, см. Участие в профильных выставках, семинарах, конференциях.
Осуществлять деловые коммуникации, в том числе на английском языке
Осуществлять деловые коммуникации, в том числе на английском языке - а не жирно ли будет на английском? Пусть русский изучают, ибо нефих ломать голову с этим «китайским» или «новозеландским» английским.
А вообще любые коммуникации следует сводить к необходимому и достаточному минимуму, пора отвыкать от пустых и ненужных тусовок.
Некоторые выводы по трудовой функции «3.6.1 Поиск путей повышения качества выпускаемой технической документации (F/01.7)»
Здесь придется прерваться, поскольку статья становится громадной и нечитаемой. Продолжение последует.
