Подготовка технической документации *

Доброго дня всем.

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

Кажется в кино кризис — хороших фильмов один на сотню. Могу предложить один сюжет — психологический триллер. Сценарий для него будет начинаться со строк: «Была у нас одна легаси-система. Монолитная. И задумали мы провести миграцию...»

Предполагается, что имеется репозитарий (repository, хранилище данных) корпоративной архитектуры, например, в виде файла excel или источника, связанного по ODBC.

Задача: на основе данных из репозитария, содержащего объекты архитектуры предприятия (процессы, орг-структура, активы и т.п.), автоматически построить схему архитектуры: сгенерировать дерево на основе данных об иерархии объектов. Рассмотрен инструментарий excel и visio (сторонних add-in), приведена сопутствующая критика этих Microsoft-инструментов.

Генерация структурных схем штатным мастером Орг-диаграмм visio по данным excel (ODBC) аналогична табличному csv или скриптовым языкам dot, mermaid, plantUML в инструментах graphviz и drawio, а также rdf-триплетам (linked data), визуализируемым через RDF grapher. Генерация штатным мастером ограничена древовидными структурами, но использование visio VBA позволяет устранить ограничение древовидности, «Но это уже совсем другая история».

В предыдущей статье Простая Enterprise Architecture. Архитектура компании садоводов было рассказано про само понятие «корпоративная архитектура» (что такое Enterprise Architecture, ЕА) и объект архитектуривания (корпорация садоводов, СНТ).

В том примере нужно было вручную рисовать архитектурные схемы (структурные и VAD – цепочка добавленной стоимости) и далее связывать данные excel c фигурами visio в ручном (путем перетаскивания строк из поля «Внешние данные») или в автоматическом (автоматическое связывание по ID) режиме. В этой статье обойдемся без ручной работы: будет показан пример технологии автоматического построения иерархической схемы по данным, хранящимся в репозитарии - файле excel (аналогично автопостроение возможно из базы данных, иных источников ODBC).

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

В материале расскажу, какие в этом вопросе бывают подходы, их плюсы и минусы, и какого подхода придерживаемся мы.

Требования ГОСТов относятся не только к оформлению документов, но и к их содержанию. В частности, ГОСТы определяют смысловое наполнение всех разделов, а также требования к изложению текста документа.

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

В далёком 2021 году нас пригласили поучаствовать в проекте по модернизации одного крупного горно-обогатительного комбината. В назначенный день мы вылетели в сторону Дальнего Востока. О том, что из этого вышло и почему словосочетание "3D сканер" заставляет наших конструкторов быть вдвойне более внимательными, читаем внутри!

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

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

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

Так оно или нет? Можно спорить, можно смотреть на опыт внедривших стран. Я же постараюсь описать типовые ошибки при проектировании и разработке систем, хранящих Единый Идентификатор.

Привет всем! Я работаю техническим руководителем в IT компании и хочу рассказать о нашем опыте использования ChatGPT в виде телеграм бота с искусственным интеллектом для решения рабочих задач.

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

Ради эксперимента я решил создать телеграм бота на основе чата GPT и использовать его для выполнения задач. Несмотря на начальное скептическое отношение, мы были приятно удивлены эффективностью Смитти (имя нашего бота).

Вначале мы делали документацию в Word, потом в Google Docs, потом в Confluence, потом была попытка написать openapi-спецификацию для API вручную, но увидев сколько всего там нужно было писать - бросили эту затею.

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

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

Всем привет! Меня зовут Антон, я 9 лет занимаюсь документацией для программистов и год работаю техническим писателем в IT-департаменте Банка РНКБ. За это время у меня сложилось своё видение «хорошей» документации и методики её разработки, и я решил поделиться им с вами.

Планирую рассказать всё в двух статьях. Сегодня поговорим о документации для IT-департамента — той, которую распространяют в электронном виде, размещают на отдельном сайте и которой пользуются программисты, тестировщики, аналитики и руководители отделов. Помимо своего опыта, покажу примеры, статьи и исследования на тему ведения документации, которые помогли мне — и могут пригодиться вам.

Все мы думаем, что хорошо говорим и пишем на своём родном русском языке. Не зря же в конце концов мы столько учились, да и в деловой переписке у нас всё вроде бы вполне неплохо. Но знаете ли вы о том, что даже для написания IT-документации есть свои правила? Поэтому сегодня в блоге ЛАНИТ на Хабре мы поделимся знаниями о русском «документном» языке. 

Чтение ФТ — занятие непростое. Восприятие новой информации и её анализ требуют продолжительной концентрации и расходуют главный ресурс IT‑шника — внимание.
Если текст сложный, читатель спотыкается в нём и увязает, перечитывает по несколько раз, тратя время и ресурс внимания.

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

Привет, Хабр! Меня зовут Татьяна Шуравина, я системный аналитик Innovative People, работаю на проекте в банковском секторе. Вместе с командой оптимизируем и автоматизируем операции сотрудников банка для обслуживания юридических лиц. В своей первой статье я рассказывала, как стать системным аналитиком без специального образования. Сегодня хочу поделиться с теми, кто начал свой путь в аналитике, тонкостями магического процесса ведения проектной документации. Не для кого не секрет, что зачастую бывает такое, что система есть, а документации, чтобы понять, как она работает, нет. В статье расскажу, какие есть подходы к ведению документации, зачем это нужно и поделюсь практическим опытом.

Привет! Меня зовут Андрей Гладилин, я работаю в Swordfish Security над составлением технической документации для ИТ-решений. Нравится нам это или нет, но она сопровождает каждый этап разработки и эксплуатации ПО. Работая над десятками и сотнями описаний ежедневно, я отметил ряд особенностей и сделал полезные выводы. И здесь постарался разобрать все ключевые аспекты, влияющие на качество технической документации, и дать практические рекомендации по его повышению. Этот материал поможет техническим писателям, менеджерам и разработчикам создать документацию, которая точно будет работать.

Всем привет. Меня зовут Таня, я работаю системным аналитиком в МТС. В этой статье я расскажу о том, как писать документацию для разработки микросервисов. 

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

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

Привет, Хабр! Меня зовут Евгения Пономарева, я руководитель проектного офиса “Цифровых технологий”, ИТ-”дочки” ДОМ.РФ. В этой статье я расскажу о роли технической документации и роли технического писателя в IT-проектах ДОМ.РФ, а также поговорим о том, как построен процесс документирования в Институте развития, и как измерить качество документации.  

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

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

Еще есть ГОСТы 34 и 19 — там уже написано, из каких разделов должен состоять стандартизованный документ, но ведь кроме стандартизованных есть и другие документы — во всяком случае заказы на таковые ко мне приходили, — и каждый раз приходилось ломать голову.