Comments 26
Я сталкивался с таким заблуждение на уровне техлида, что код должен быть самодокументируемым) каким-то волшебным образом человек должен понимать бизнес логику через её отражение в коде. Я стараюсь оставлять пару строчек на неочевидных моментах или оставлять @see-ссылку на таску. Вопрос-а существует хороший фреймворк для связи кода и документации? Типа оставляешь в код ссылку-атрибут на якорь в доке .md и можешь прыгать туда-обратно?
Документация нужна, должна быть, поддерживаться и сопровождаться.
В идеале -- да. И к нему нужно стремиться. Мы так и делаем.
Но почему-то все равно хочется сказать "но")))
Да, я вас прекрасно понимаю. Все дело в золоте стоимости содержания. Если на текущих специалистов раскидать роли по обслуживанию документации, то скорее всего у них будет недостаточно опыта (научатся, но не сейчас) и времени, если нанять (качество найма тоже влияет) специализированный штат, то это дорого - должно быть обоснование таких затрат (эффект выгоды на полезность). Даже в идеальном штате, все может рассыпаться из-за неумелового руководителя..
Поэтому и есть этот внутренний "но"..
Но (каламбур), как и во многих других сферах бытия, мы должны двигаться к цели даже если никогда её не достигнем. Сравнивать опыт друг друга с точки зрения близости достижения этой цели..
Какие хорошие механизмы есть для того, чтобы не полагаться на совестливость и отличную память людей в вопросах поддержания актуальности документации? Definition of Done и скрам-мастер с дрыном? Или что-то более технологичное существует?
Версионирование, как одна из хороших практик.
Есть слои версий: версия продукта (пакета), релиза, компонента, сервиса, апи, документа.
Если построенны процессы, то на этапе планирования готовится ~60% всего, а волна апдейтов версий завершает в конце задуманное.
Ретроспективы и ревью/демо как контрольная точка с чек листом.
Если составлять документацию до написания кода, то она всегда будет актуальной.
Примечательно, что с точки зрения автора Ops не существует, только Dev и заказчики/пользователи.
"Несовершенство закона российского умаляется их повсеместным неисполнением»
*
Вы с какой целью запугиваете народ такими канцелярскими текстами? Вся нормативка уже давно существует. Игнорируют ее.
*
Причины тоже известны: а) большая загрузка; б) сознательное поддержание беспорядка и неполноты с целью повысить собственную стоимость в глазах начальников.
*
Методы борьбы (или просто нормальной работы) - ставьте задачи в трекер с признаком "требует документирования". И требуйте исполнения.
*
Вы не сказали о самом, нмв, главном. Документирование - это сохранение и накопление знания.
Автор, расставте п этой статье ссылки на ГОСТы. Воможно вы увидете ещё одну проблему. А так тема ещё та...
Чуть-чуть помогу автору))) Проблема будет в "точке зрения" на документацию и систему (АС и предприятие). Все (руководство, подчиненные и ИТ) хотят видеть именно свою часть (отчетность, кнопочки, алгоритмы). Всё изменения системы, в виде отдельных задач, теряются, дублируются или противоречат друг другу... нужно, как то, переходить к единой БД знаний и спецификаций.
Ниже, приведена только часть стандартов из коллекции. OpenAI , как то не спешит оцифровывать и структурировать Стандарты... титьки то важнее 😊
Начнём с идентификации Документов:
ГОСТ Р 55681-2013 Информация и документация. Анализ процессов работы с точки зрения управления документами
В рамках управления ЖЦС, выделяют следующие Родовые типы информационных объектов.
ГОСТ Р 57098-2016/ISO/IEC TR 24774:2010 Системная и программная инженерия. Управление жизненным циклом. Руководство для описания процесса
Примеры информационных объектов из 15288 (ЖЦС)
ГОСТ Р 57193-2016 Системная и программная инженерия. Процессы жизненного цикла систем
Метаданные документов по мнению СИБИД:
ГОСТ Р ИСО 23081-1-2008 СИБИД. Процессы управления документами. Метаданные для документов. Часть 1. Принципы
Версия спецификации MoReq2
ТИПОВЫЕ ТРЕБОВАНИЯ К УПРАВЛЕНИЮ ЭЛЕКТРОННЫМИ ДОКУМЕНТАМИ
Процессы управления документами:
ГОСТ Р 7.0.101-2018/ИСО 30301:2011 ИНФОРМАЦИЯ И ДОКУМЕНТАЦИЯ. СИСТЕМЫ УПРАВЛЕНИЯ ДОКУМЕНТАМИ. ТРЕБОВАНИЯ
Спецификация Требования, Документ:
ГОСТ Р 57323-2016/ISO/TS 15926-11:2015 Системы промышленной автоматизации и интеграция. Интеграция данных жизненного цикла перерабатывающих предприятий, включая нефтяные и газовые производственные предприятия. Часть 11. Методология упрощенного промышленного использования справочных данных
Состояния требования стейкхолдера:
ГОСТ Р 57195-2016 Ядро и язык для методов системной и программной инженерии. Общие положения
Процесс анализа требований
"ГОСТ Р 57318-2016. Системы промышленной автоматизации и интеграция. Применение и управление процессами системной инженерии
Синтаксис требования:
ISO 29148
Управление знаниями:
ГОСТ Р 57133-2016
К документации по управлению проектам, требования см тут:
Скрытый текст
Большое спасибо за материал.
По поводу "точки зрения" на документацию, также как каждый руководитель департамента хочет видеть только своего департамента, есть руководитель руководителей всех департаментов и он должен организовать их работу "как единый организм" , согласно стратегии.
Вот тут, поясню свою точку зрения. Нет такого руководителя всех руководителей и "единого организма" (уже всё можно передать на аутсорс)... нельзя Генералу заниматься с новобранцами строевой подготовкой, у него задачи другие... Иерархия нужна не для лычек... Каждый должен знать и понимать Ответственность и Полномочия. ГД не имеет права заставить рабочего лезть в "огонь" без СИЗов и инструкции "по лазанию в огонь")) или самому лезть...
схема 1
Рассматривая схему 1, с ТЗ предприятия (Sys of Int), то на каждом этапе ЖЦ предприятия ответственность за него несут разные системы (их владельцы).
Concept - уровень стейкхолдера, акционера;
Dev - ГИ или строители (для примера РОСАТОМ, только он умеет строить АЭС);
Prod - уровень директора, здесь предприятие уже должно работать и давать результат (выполнять цели/стратегию Concept).
А вот при управлении подразделением, важно "контролировать" не только свою деятельность (подчинённых), но и Входы в процесс (поставщиков). Но воздействие, на Систему (её босса), которая предоставляет что то на Вход, руководитель не может, у него таких полномочий нет... Вот тут то и появляется Надсистема (соотв ЗГД или ГД), которая имеет такие полномочия, для Изменения Системы поставщика входа (см схема 2).
схема 2
9001, 15504
И вот, где то во всём этом, аналитику нужно "найти" спецификацию требований к ИС и не сойти с ума)...
Как нет? Глобально ИТ организацию можно поделить на область CEO и область CTO/CIO. А они уже строят свои департаменты с руководителями. С-lvl и обеспечивает достижение целей в одной единой стратегии.. У каждой позиции своя роль, свой вклад, свои обязанности по работе/созданию/поддержке документации.
А то как же это работать если каждый, пытается любой кусок в свой подпол тянуть... Не работа а "дряньство" выходит
А что касается аутсорса, так это не отменяет концепции. Ваша (команды) зона обязанностей сокращается, при этом перекладывается на качественный выбор аутсорсера и совместимости стандартов его и ваших. Сделает ли он по продукту документацию которая отвечает на все ваши требования? Обычно пользуются тем что дают.. Ни разу не видел контракт не подписанный из-за согласования формата документации. Сразу скажу опыта работы в гос структурах не имею.
ИТ организацию можно поделить на область CEO и область CTO/CIO... С-lvl и обеспечивает достижение целей в одной единой стратегии..
Можете показать профстандарты на эти роли, я не понимаю чем они занимаются (кроме получения большой ЗП). Где ДИ или ПСП? Я опираюсь на общепринятые документы, утвержденные на гос уровне. По ним строят танки, самолёты и АЭС. А всякие СЕО только чаты ЖПТ сделали... Не сравнивайте производство с деньговыкачиванием.
Мне (как ИТ) когда то в Трансгазе сказали: "-Труба качала и без Вас!"
А они уже строят свои департаменты с руководителями.
Ну это везде так, просто я про то, что через голову прыгать нельзя...
Сделает ли он по продукту документацию которая отвечает на все ваши требования?
ITIL. Если в соглашении пропишите, то будет.
Обычно пользуются тем что дают..
Вам, как исполнителю, дают не они, а директор, который заключил соглашение... он наёмщик. откатик получил и доволен)) Вы же айтишники, разберётесь... а если нет, то куда вы пойдёте жаловаться?? Стандарты то не обязательные... пара-пара-пам-поу
опыта работы в гос структурах не имею.
там хуже.
*Сейчас нету ни возможностей, ни целей делать качественное и дешёвое ПО.... Где то, про микро транзакции в играх, говорили ~"вы платите, они их больше делают"
Скажите, пожалуйста - а как обстоит дело с имплементацией этой коллекции в конкретные инструменты, кейсы, бизнес-процессы? Очевидно, что она выстраивается системно. (Есть подробности о положенной в основу системе?) Но сама эта система не очевидна на уровне предприятий и компаний. Ее нужно закладывать в специализированные программные продукты, выпускать рекомендованные БП и пр. Нельзя разрешать разрозненные и неверно интерпретируемые попытки делать это по принципу "кто в лес, кто по дрова". Как с этим?
Часть 1, см комментарии выше ⬆.
"Границы ключ переломлен пополам, А наш батюшка Ленин совсем усоп..."
Разделение труда. Отраслевые стандарты. Профессиональные стандарты.
Ну оркестр, как то справляется с нотами, разными инструментами и без специализированного ПО. Всё тоже самое. Делаешь так, как написано в ДИ то, что установлено в ПСП в соответствии с планом работ. Бюрократия - это как демократия, только главные не толстосумы, а Документы. Как и всё хорошее, с бюрократией расправились ещё в 90е... дак Бюрократия это зло или нет?!
Идентифицируйте все документы организации (БД это тоже документ, построчно) по ГОСТ Р 55681, идентифицируйте Системы по 57193(15288), идентифицируйте процессы по ГОСТ Р 57098... и всё
дальше берём ГОСТ Р 9001 и обеспечиваем Качество...
"кто в лес, кто по дрова"
Водитель лесовоза едет в Лес, а вот лесорубы по Дрова... они не разбираются в работе друг друга и не лезут с советами (хорошо бы)... Но все участвуют в одном процессе. НО! тк они едут в лес, то для Медведя это уже просто Риск/Возможность.
Если вы, хотите помочь директору, то незачем, не поделится)). Если Вы директор, то обратитесь к Системному инженеру или Инженеру СМК. Очень сложно "прыгать" из операционного управления в управление системами (да ещё и под пивко)
Советую прочитать "Оргуправленческое мышление" Г. Щедровицкого
Организация, руководство, управление как типы деятельности
Я коротко задам сравнительные характеристики организации, руководства и управления.
Организация является по сути дела конструктивной работой, материалом которой становятся люди. При этом слово «организация» употребляется в двух смыслах: организация как деятельность организовывания и организация как результат этой работы.
При организовывании мы собираем нечто. У нас должны быть какие-то конструктивные элементы, конструктор с набором элементов, и мы должны, с одной стороны, определенным образом собрать эти элементы и с другой — установить между ними те или иные связи и отношения. Когда мы проделываем такую работу, то мы накладываем определенную организационную форму на эти элементы. Мы можем производить организацию за счет состыковки их друг с другом, а можем еще задавать специально связи, скреплять их тем или иным способом. И когда мы проделали такую работу по объединению элементов и установлению между ними определенных отношений и связей, мы эту работу прекращаем, и дальше организованное нами целое может начать жить по своим законам. Но его жизнь по своим законам уже не принадлежит организационной работе, работа по организовыванию состоит только в том, что мы набираем определенные элементы, собираем их и устанавливаем между ними определенные отношения и связи.
Что такое управление и в каком случае мы осуществляем управление? Можно ли, скажем, управлять стулом? Нет, говорю я. Его можно поставить, можно его двигать, можно его поломать, преобразовать. Это будет определенная практическая, преобразующая деятельность. Но это каждый раз не управление.
Теперь более сложный случай - машина. Вот машина стоит, вы на акселератор еще не нажали — можно ли управлять ею? Нельзя. А когда появляется возможность управлять машиной? Когда она поехала. Управление возможно только в отношении объектов, имеющих самодвижение. Пока этого самодвижения нет, ставить такую задачу или цель - управление - не имеет смысла.
Можно представить себе ситуацию, когда можно управлять полетом стула. Представьте себе что-то вроде мушкетерского побоища: кто-то бросает стул, и я, вместо того чтобы от него защищаться, направляю его полет несколько в другую сторону. Я осуществил одноразовый, одномоментный акт управления - изменил направление полета стула. В этом смысле я осуществил управление этим процессом. Но смотрите, чем я управлял? Я управлял полетом стула, а не стулом.
А теперь о руководстве. Руководство возможно только в рамках организации, в рамках специальных организационных связей. В чем состоит суть руководства? В постановке целей и задач перед другими элементами. Но для того чтобы я мог ставить цели и задачи перед другими элементами - людьми, нужно, чтобы они от своих собственных целей и задач отказались и обязались бы принимать мои цели и задачи. И именно это происходит в рамках организации.
Организация людей - я возвращаюсь назад к организации и фиксирую ее свойства и качества - всегда осуществляется таким образом: человек, занимающий определенное место, отказывается тем самым от собственных целей и задач, от собственного самодвижения и обязуется двигаться только в соответствии с этим местом и соответственно тем целям и задачам, которые по каналам организации будут передаваться ему вышестоящими инстанциями.
В.И. Ленин, справился, даже, без смартфона и компутера...
ГОЭЛРО
ГОЭЛРО — государственный план развития электроэнергетической отрасли в Советской России после Октябрьской революции 1917 года. Разработан Государственной комиссией по электрификации России по заданию и под руководством В. И. Ленина.
на сегодня всё)
С лесом и дровами ваш ответ неудачный, нмв. Это называется "вертикально интегрированная компания", если делать по уму, а не просто гнать кругляк восточному соседу.
Мне ведь это не для работы. Я пытаюсь оценить уровень работы по документированию и управлению знаниями на уровне головных организаций по разработке стандартов.
То, что вы ответили, расстраивает. Про дедушку Ленина я в курсе. Но ситуация, когда "писатель пописывает, а читатель почитывает" уже представляется out-of-date.
Вы же про систему не ответили. И это огорчение №1. Должна выстраиваться система. Помните, на предприятиях были ОНТИ? Были реферативные журналы по отраслям. Много чего было. И это была система.
Вы же даете море ссылок на ISO и не говорите про систему. Означает ли это, что мы некритично следуем в кильватере за ISO? Означает ли это, что все руководители на уровне директоров крупных предприятий, холдингов, замминистров и министров согласны с таким подходом? Желания сделать с учетом мирового опыта на новом уровне систему работы с информацией, знаниями, доками, стандартами нет? У нас вроде в СССР был достигнут в этой области неплохой уровень?
Вы упомянули OpenAI. Я полагаю, что нужно имплементировать открытую LLM, обучасть ее на массиве действующих стандартов - и давать доступ для всех работников этой сферы. А вы мне про дедушку:(
Если вы хотите добиться единомыслия в России (а стандартизация именно об этом), то в идеале нужно делать госпрограмму. Делать базовое ПО, к нему набор плагинов по каждому ГОСТу (чтобы собирать конфигурацию под себя). И не на стороне, а с головным институтом по стандартизации, чтобы была именно корректная и полная имплементация системы стандартов. А не левая интерпретация неизвестно кого. И вводить ее как обязательную (типа системы бухгалтерской отчетности) для всех. С конкретными комплектами стандартов по отраслям (если необходимо).
Тоже самое по управлению знаниями. Но там, я так понял, вообще конь не валялся, да?
нету никакого "Уровня"... есть яма;
вы же всё правильно пишите: "Должна", "были ОНТИ", "была система"... сейчас то нету;
я не могу давать море ссылок, в моей коллекции их ~600... СССР больше НЕТ! Бюрократия - это зло... Да, стандартизация всем мешает воровать;
Нужно, согласен... но я, бесплатно и к тому же в одну каску, работать не буду/не смогу... Дедушку, поддержал рабочий класс, а вы готовы пройти аттестацию на соответствие профстандарту??;
М. Мишустин вроде, как системщик, должен это понимать... Г-ны Греф и Миллер этому противостоят, как могут... SAP - это же престижно)))
там медведь валялся... вы же всё понимайте)))
А куда у вас редуцировался п.1? :)
Ну, я по крайней мере свой профстандарт читал. Наверное, смогу, только вспомнить надо
Но тогда, выходит, подтверждается моя догадка о том, что процитированные вами ссылки - это продукт стаи товарищей, захвативших важный опорный пункт. А не системный подход к стандартизации.
И еще раз подчеркну, что внедрение стандартов без современных программных продуктов выглядит просто растаскиванием денег. Типа "я прокукарекал, а после меня хоть потоп". Печалька.
Но в целом это выглядит странно. У нас же явно прослеживается стремление (по стопам умных американцев) везде вводить протоколы лечения, регламенты, инструкции и прочие подзаконные акты. Система поборов с граждан в виде штрафов за любой чих вообще на заглядение. И при этом "забить" на приоритетное развитие системы стандартов...
А куда у вас редуцировался п.1? :)
дак там уже про кругляк речь пошла... а я больше по плотникам))
"кильватере" "редуцировался" "имплементацией"
у вас есть обязательный к использованию список с такими словами?)))
Но тогда, выходит, подтверждается моя догадка о том, что процитированные вами ссылки - это продукт стаи товарищей, захвативших важный опорный пункт. А не системный подход к стандартизации.
нет. со стандартами всё Ок. Они между собой взаимосвязаны и ссылаются друг на дружку... Ещё раз, они работают, если их применять (см "мартышка и очки").
внедрение стандартов без современных программных продуктов выглядит просто растаскиванием денег
Вот прямо противоположное. Если, вы не можете внедрить системный стандарт без ИТ, это плохо. Система, в первую очередь, это документы.
Я не про стандарты разработки ИТ систем, тут понятно (Эксель, это не автоматизация).
(по стопам умных американцев)
полегче... я, про ГОЭЛРО, могу ещё раз повторить... Н.Винер и Э.Деминг, это "рестайлинг" под американизмы... убрали все советские термины и всё.
Посмотрите кто занимался системотехникой в СССР и где они находились (ВУЗы), поймёте, что эта работа была сделана не за один день, а с*ка системно продолжает проводится до сего дня.
Вы писали: "нет. со стандартами всё Ок. Они между собой взаимосвязаны и ссылаются друг на дружку... Ещё раз, они работают, если их применять"
Удивлен вашим пониманием того, что такое "ОК". Одна из причине не использования (или "кривого" использования") стандартов в том, что суть полностью понимает разработчик. А пользователь вынужден расшифровывать это послание. Но разработчику - по вашей логике - это уже до лампочки. Стандарт ведь ОК? Все, дальше сам, сам. Тогда дальше не вижу смысла. Успехов.
Если у доки нет читателя, то она не нужна. А если есть, то он должен за нее "платить". И под него должен настраиваться формат этой доки.
"Описания организационных процессов, процедур и политик, таких как стандарты разработки, процессы управления проектами и процедуры контроля качества."
Это нормативно-техническая документация.
Организационная — это уставы, штатные расписания, трудовые договоры, правила внутреннего распорядка, многие другие документы, создаваемые внутри компании на основании действующего законодательства.
Документации быть