Пришло время освежить эту статью, включая ее название. Библиотеки взаимоувязанных документов для AuthorIT безусловно полезны тем, кто пользуется программой AuthorIT для разработки технической документации. Но таких счастливцев, к сожалению, найдется немного, а счастливчиков - владельцев AuthorIT Workgroup Edition - и того меньше. Поэтому речь пойдет о замене инструмента, редкого и относительно дорогого AuthorIT, на широко распространенный и практически бесплатный Atlassian Confluence путем воспроизведения последним функциональных возможностей первого.
Кому все это надо? В явном виде тем, кто непосредственно занимается писаниной, в неявном - ВООБЩЕ ВСЕМ участникам проекта, даже заказчику. Ведь ни для кого не секрет, что без громадного количества бумаги не обходится ни один даже самый простенький проект. Редакция от 13.11.2021.
Создан 01.03.2018 11:06:45
В настоящий момент наработан целый ряд библиотек для AuthorIT, позволяющих существенно автоматизировать разработку технической документации, а именно:
- библиотеки взаимоувязанных документов, разработанные согласно ЕСКД, в частности, по ГОСТ 2.601, ГОСТ 2.610, включая ссылочные стандарты. Модификаций множество - от совсем простых специфицированных и неспецифицированных изделий (вроде лопаты или лома) до систем пожаротушения и интегрированных систем безопасности;
- библиотеки взаимоувязанных документов, разработанные согласно 34 комплексу стандартов. Модификации - системы коммерческого учета электроэнергии, всевозможные медицинские системы, Интернет-порталы различного профиля (вплоть до федерального уровня) и пр.;
- библиотеки взаимоувязанных документов, разработанные согласно ЕСПД.
Библиотека взаимоувязанных документов на базе ЕСПД включает в себя практически все документы по ГОСТ 19.101.
Виды программных документов и их содержание приведены в таблице.
Вид программного документа | Содержание программного документа |
Состав программы и документации на нее | |
Перечень предприятий, на которых хранят подлинники программных документов | |
Запись программы с необходимыми комментариями | |
Сведения о логической структуре и функционировании программы | |
Требования, подлежащие проверке при испытании программы, а также порядок и методы их контроля | |
Назначение и область применения программы, технические, технико-экономические и специальные требования, предъявляемые к программе, необходимые стадии и сроки разработки, виды испытаний | |
Схема алгоритма, общее описание алгоритма и (или) функционирования программы, а также обоснование принятых технических и технико-экономических решений | |
Эксплуатационные документы | Сведения для обеспечения функционирования и эксплуатации программы |
[из 2.2 ГОСТ 19.101-77]
Виды эксплуатационных документов и их содержание приведены таблице.
Вид эксплуатационного документа | Содержание эксплуатационного документа |
Перечень эксплуатационных документов на программу | |
Основные характеристики программы, комплектность и сведения об эксплуатации программы | |
Сведения о назначении программы, области применения, применяемых методах, классе решаемых задач, ограничениях для применения, минимальной конфигурации технических средств | |
Сведения для проверки, обеспечения функционирования и настройки программы на условия конкретного применения | |
Сведения для эксплуатации программы | |
Сведения для обеспечения процедуры общения оператора с вычислительной системой в процессе выполнения программы | |
Описание синтаксиса и семантики языка | |
Сведения для применения тестовых и диагностических программ при обслуживании технических средств |
[из 2.3 ГОСТ 19.101-77]
Далее: |
Некоторые уточнения:
- Ведомость держателей подлинников - отсутствует за невостребованностью;
- Руководство по техническому обслуживанию тоже отсутствует. Почистить пылесосом кулеры или протереть салфеткой экран можно и без руководства;
- Описание языка - отсутствует как неактуальный. Никто не станет, к примеру, расписывать язык С++, поскольку всегда можно указать ссылку на соответствующий стандарт.
Дополнительно в библиотеке присутствует множество различных терминологических стандартов, позволяющих организовывать сноски с определениями применяемых в документах терминов.
Заинтересованные стороны - участники проекта, или кому что надо и не надо
Нерукотворный памятник прошлому воздвигли, дань отдали, теперь о том, кому что надо или не надо.
В первую очередь все это надо техническому писателю - ему точно не придется ОСОБО ДОЛГО объяснять, для чего все это ему надо, достаточно посмотреть картинку.
Топик «_3.1 функциональное назначение программы или программного изделия_2.3 ГОСТ 19.201-78» встречается в десяти программных документах, а еще разок среди задач проекта. Без вариантов: либо каждый раз копипастим этот топик в десять документов при малейшем изменении функционала программы, либо единожды внедряем его в структуры документов и больше не паримся всю оставшуюся жысь.
А кто вообще должен определять функциональное назначение программы? Ну уж точно не техпис, смотрим 5.3.1 Процесс планирования содержания проекта ГОСТ Р 54869-2011, а затем картинку ниже и выясняем, что
функциональное назначение программы или программного изделия определяется руководителем проекта!
Иными словами, в ходе выполнения любого проекта документированием «повязаны» все без исключения участники проекта. И задача техписа тут стодвадцатьпятая и чисто редакторская - просто привести в порядок текст функционального назначения, примерно так, как это расписано ниже.
- автоматическое формирование запроса (ссылки), содержащего заголовок (title) текущей страницы в качестве фактического параметра;
- автоматизированная отправка запроса в онлайновые сервисы поиска;
- автоматическое формирование запроса (ссылки), содержащего адрес (URL) текущей страницы в качестве фактического параметра;
- автоматизированная отправка запроса в онлайновые сервисы анализа.
Но как всегда - имеется одно «НО». Техпис, быть может, сам того не осознавая, КРОВНО заинтересован документировать автоматизированно, а не тупо копипастить, плодя ошибки, за которые его же впоследствии и поимеет руководитель проекта. А сам РП как заинтересован, так и не заинтересован в автоматизированном документировании, причем одновременно и в любой произвольно выбранный момент времени.
И по большому счету РП абсолютно фиолетово, сколько крови, пота и слез прольет бедняга-техпис, ему важно - да ничего ему не важно. Хотя...
Штихель штихелю - рознь!
С руководителями у нас вообще песня. Кто-то «из крестьян», кто-то «поставлен на кормление», а кто-то просто митрофанушка. Первые еще что-то пытаются делать, вторым все пофигу. Третья категория - «а ты мне не дашь ту свою программку, которая сама ТЗ пишет?» 😂
Да простит автора статьи автор картинки (при всем своем неоднозначном отношении автора к автору), но тут он попал в самую точку. Нагло стырено из открытых источников, а потому претензии не принимаются, ежели что.
Итак, «Бурлаки на Волге» - это, как догадались особо проницательные, те самые, что «из крестьян». По какой-то странной иронии судьбы среди них встречаются все больше выпускники Академии РВСН и Академии им. Жуковского (сейчас сии достойные заведения называются слишком уж вычурно, проще звать их как прежде, по старинке).
Это закаленные ракетным топливом и керосиновой аэродромной гарью люди, изучавшие теорию вероятности если не на лекциях, то по книгам Елены Сергеевны Вентцель, способные косить траву лопатой и даже ломом, но охотно признающие, что отточенной лопатой все же сподручнее. А газонокосилкой еще и быстрее. И если поручик Ржевский ценил не столько результат, сколько процесс, то бравые подполковники запаса - с точностью «до наоборот». Им важен результат. Любой ценой.
А если серьезно, то их подходы к выполнению любого проекта сродни «методу последовательного приближения», не имеющему никакого отношения к численным математическим методам. Суть его состоит в том, чтобы регулярно идти к намеченной цели очень маленькими шажками. А еще их крайне тревожит то, что скажет княгиня Марья Алексеевна - полковница и начальница военного представительства.
Применительно к проведению ОКР согласно ГОСТ РВ такому-то метод реализуется так: один экс-подполковник обеспечивает общее идеологическое руководство («нам надо бы вот так именно сейчас»), другой играет роль исполнительного директора, ставящего задачи молодежи: Петя у него регулярно согласовывает шажок с ВП, затем Вася создает уже согласованную задачу в какой-нибудь Jira, а «юркий» Фима Цейтлин обосновывает созданную задачу аутентичным текстом того самого ГОСТ РВ, «копипастя» его в описание задачи Jira, а то и просто вручную создавая таблицу шагов в ворде. И так далее «по команде». Это и есть «комплекс средств автоматизации».
В общем, «Эй, ухнем! Еще разик, еще раз!». Воюем не умением, а числом.
Наверное, привычная технология в чем-то и оправдывает себя, но автору все это как-то в диковинку: не проще ли загрузить текст стандарта в синтаксический анализатор, заполучить за минуту структуру декомпозиции работ, согласовать ее с княгиней Марьей Алексеевной, после чего слить задачи единым пакетом в ту же Jira?
Обломову и хотелось бы...
...чтоб было чисто, да он бы желал,
чтоб это сделалось как-нибудь так,
незаметно, само собой...
«Обломов» © И.А. Гончаров
Олег Павлович Табаков - лучший Обломов всех времен и народов...
«- Помилуй, а Обломовка? Триста душ!» - ну триста не триста, а поменее их в департаменте будет, но рублей двести-триста ежемесячно приносит, причем без особых беспокойств. И без напряжения.
В чем задачи тех, что «поставлены на кормление»? Блюсти баланс в среде других «парашютистов», «благопристойство» внутри заведения, да придерживать за шиворот тех, что из крестьян, дабы место свое знали, не огорчать и не доставлять беспокойства своим протекторам. Собственно, все.
Почти все. Еще представительствовать при встречах с потенциальными заказчиками, снисходительствовать с потенциальными исполнителями составных частей ОКР и ратовать за научную организацию труда, за все передовое и прогрессивное против всего отсталого и регрессивного.
Таким образом, автоматизироваться вроде бы и любопытно, но да и шут с ней, с этой автоматизацией и механизацией. Будут напряги с проектами - отменим очередные отпуска, новогоднюю двухнедельную пьянку, пообещаем холопам премии, оплатим работы в выходные - все дешевле обойдется, чем чему-либо способствовать и, тем более, принимать на себя столь высокую ответственность за судьбы! Пусть играются в свою автоматизацию, а там как пойдет.
Что касается митрофанушек, то их и на кормлении уже с трудом удерживают. Совсем уж ничего не тянут.
Мораль
Получается, что «больше всех надо» непосредственным участникам документирования. Но и им особо и не надо 😂
Ведь как планируется проектная деятельность в более-менее пристойных заведениях? Вовсе не канбанными досками, а ленточной диаграммой. Если мыслить традиционно-каскадно, то основная пейсательская деятельность приходится на стадию рабочего проектирования, сразу после «4.1.1 ПрограммированиЯ и отладкИ программы», если все идет хотя бы по ГОСТ 19.101. А в особо продвинутых конторах вообще в рамках некой задачи внедрения, см. рисунок ниже.
Если учесть неоднократно подтвержденный и неопровержимый факт, что все эти руководители-эксперты-программисты и прочие проектные деятели склонны «жевать Муму» в ходе проекта, то беднягам-пейсателям попросту ни на что не остается времени. Предшественники его нещадно сжирают.
А кто виноват? Конечно, писатели, они же со своей задачей не справились. Не выдали толковую и грамотную документацию, а ведь документация - это «лицо» проекта! А они это лицо мордой в грязь...
Но не пройдет и тридцати лет, как «те самые два процента» от тех самых участников проекта сообразят, что документация может делаться «как-нибудь так, незаметно, само собой», стоит только один раз напрячься и озадачиться «комплексной автоматизацией и механизацией» проектирования и документирования. Тогда и диаграмма Гантта станет выглядеть совсем иначе, и времени всем хватать будет, и лицо проекта будет сверкать, как с обложки глянцевого журнала.
Автор, скорее всего, не доживет до этих славных времен. И если читатель входит в «те самые два процента», то обязательно изучит во всех деталях статьи-«сиблинги» в этом же разделе.
