Напишу-ка я очередную проповедь про программистов – точнее, об их взаимодействии с внешним миром. Глупый и наивный программист думает, что конечный результат его работы – это код программы. Программист, побитый жизнью, обычно догадывается, что код этот сам по себе малоинтересен, и к нему нужна еще какая-то документация. Если это удается сочетать с живительными пиздюлями менеджмента – то к проекту прикручивается какой-нибудь Doxygen или Javadoc, и на выходе получается автоматически сгенерированная портянка рафинированной чуши.
От следующего столкновения с реальным миром кодомакака обычно хорошо изолирована – так что она может и не подозревать, что в конечном итоге и код, и документация должны превратиться в что-то материальное. Даже веб-приложение, крутящееся в каком-нибудь AWS – так или иначе записано на материальный носитель, выполняется на вполне себе физическом сервере, взаимодействует с пользователями через каналы связи и пользовательские же устройства.
Примерно тут возникает еще одна проблема – “код и документация” нужны заказчику в удобоваримом для него виде. Скажем, “код валяется в разных местах на диске у Васи, документация – в виде обрывков бумажек в столе у Пети” ни одного заказчика не устроит; “исходники и Javadoc лежат на гитхабе там-то и там-то” – приемлемый вариант для “технарей”; “все документы по проекту находятся в CVS-системе фирмы, а также записаны на компакт-диски и находятся в двух разных помещениях архивов” – вариант повышенной энтерпрайзности, ну и так далее.
И тут мы приходим к одной поучительной истории – про ЕСПД. Идея 19 и 34 серии ГОСТов, если вдуматься – это решение проблемы, описанной в предыдущем абзаце. Если говорить на языке более современных подходов к разработке ПО – типа RUP или OpenUP – то они описывают “артефакты”, которые должны возникнуть в ходе разработки программы или автоматизированной системы, и требования к содержанию и оформлению этих “артефактов”, позволяя заказчику, разработчику и потребителю ПО говорить “на одном языке”.
Проблем с ЕСПД две – откровенный саботаж всякого процесса документирования своего творчества со стороны программистов и (как позже увидим, непосредственно вытекающая из этого) устарелость стандартов. Но начнем мы все же с саботажа. Давайте попробуем “изготовить” полагающийся по ГОСТ 19.401-78 “Текст программы”. Поймайте программиста и попросите у него “текст программы”. Ответом вам будет либо набор файлов (хорошо, если он сопровождается каким-нибудь Makefile), либо, если вы используете много “чужого” кода – долгая дискуссия, где заканчивается ядро Linux и начинаются ваши доработки. Дальше вы смотрите на ГОСТовские требования и понимаете, что распечатка ядра Linux или какого-нибудь веб-фреймворка на бумаге – это, конечно, прикольно – но отдел технической документации у вас это не примет.
Дальше выясняется – со слов коллег, сдававших сделанную по ЕСПД документацию раньше – что архив и нормоконтроль удовлетворятся сделанным в Word документом, содержащим что-то, похожее на исходники программы. Не вопрос! – думаете вы, и лихим Ctrl+C – Ctrl+V набиваете вордовский шаблон неработающими исходниками. Собственно, где-то на этом этапе в 1937 году вас бы ждал расстрел за подлог документов и саботаж (кстати, вы никогда не задумывались, что сокращение ИТР обозначает одновременно инженерно-технических работников и иностранные технические разведки?) – но сейчас времена более вегетарианские. и за такое очковтирательство никому ничего не будет.
Маленькое отступление – если бы вы не слушали “более опытных” коллег, а пошли бы в архив с тортиком, то вы смогли бы выяснить, что записанный на компакт-диск zip-архив с исходниками тоже сойдет. Впрочем, особо красноречивые товарищи могут попробовать научить работающих в архиве девушек пользоваться TortoiseHg.
Примерно так же происходит подготовка любых других документов “по ГОСТ” – вместо минимально читаемого Javadoc “Руководство программиста” будет куцей компиляцией форменного бреда; “Руководство системного программиста” будет описывать все, кроме того, что действительно нужно. В конечном итоге на написание документации будет посажена “девочка”, совершенно не задумывающаяся о сути производимой работы, но неплохо умеющая писать формально удовлетворяющую требованиям нормоконтроля документацию.
Поздравляю, вы окончательно приплыли! Через некоторое время процесс очковтирательства при подготовке документации будет отлит в граните зафиксирован не только в “организационной памяти”, но и в стандарте предприятия, и из необходимого этапа в жизни программного продукта превратится в бессмысленную и неприятную повинность (впрочем, “девочка” для этого у вас уже есть).
В принципе, с чем-то подобным столкнулись и обычные инженеры, конструктора и так далее – но в отличие от программистов, там довольно быстро осознали, что стоит привести ГОСТы в соответствие с реальностью XXI века – поэтому в ЕСКД где-то в начале 2010-х легализовали, к примеру, “электронный документ” (собственно, ГОСТ 2.051-2006 приняли еще раньше, как несложно догадаться – в 2006). Технически продвинутые программисты – наоборот, предпочитают оставаться в реалиях 1970-х годов по причине полной неспособности взаимодействовать с “нехорошими бюрократами”. Остается их с этим поздравить.
PS Написано по мотивам личного опыта автора, your mileage may vary.
![[info]](http://stat.livejournal.com/img/userinfo.gif){kind=small}
