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

Наверняка вы создавали open source проекты и выкладывали их на GitHub, но я уверен, что очень немногие из вас создавали документацию для этих проектов. В этой статье я расскажу, как создавать и публиковать доки максимально просто.

Документация будет создаваться на основе исходного кода, она будет обновляться при каждом коммите и при этом будет доступна через интернет. Документирование происходит через Doxygen, в качестве хостинга выступает GitHub, а за обновление документации отвечает GitHub Pages.

Как правило, работа с документацией — это последний этап любого проекта, связанного с данными (data science, data visualization и т. д.), проектированием и разработкой ПО. Речь о создании и редактировании библиотек, файлов README, обучающих материалов и др. Среди всех преимуществ VScode — его уникальная экосистема расширений. И особенно впечатляют те, что помогают работать с документацией. В этой статье поделюсь самыми полезными из них.

Онтологический инжиниринг в области Управления бизнес-процессами (BPM). Семантический BPM (Business Process Management), впрочем, как и семантический ЕА (Enterprise Architecture), – это заимствование концепций (подходов к описанию и онтологизации) \ инструментов Linked Data к указанным направлениям (формализация процессов и архитектур предприятий).

«Красная нить»: когда мы формализуем процессы - мы говорим об одном и том же, но на разных языках (нотациях), поэтому стандартизация Языка семантики, онтологических концептов BPM (EA) – важная, но еще недостаточно популяризированная составляющая развития BPM (следующий этап, ВРМ 3.0). Отделение («мух от котлет») семантики от синтаксиса позволит «рафинировать» понятийный (смысловой) анализ бизнес-процессов и при их аналитике оперировать базовыми (семантическими) концептами (образами). 

В Semantic BPM, как и в Semantic Web (семантическая паутина), смысл представленного процесса \ архитектуры понятен не только человеку, но и машинам и они могут его читать и обрабатывать. Эти смыслы, обычно передаваемые «человек – человек» на языке синтаксиса / графической грамматики через нотации VAD, EPC, BPMN, UML (плюс еще несколько десятков подобных вариантов \ форматов «обертывания», включая Дракон), исходно формализуются на языке семантики (стек Linked Data или аналогичный) и уже потом упаковываются в схемы с конкретной нотацией («пишутся» на языке какой-либо нотации). Для единого понимания смысловой составляющей схем применяется общая ВРМ-онтология, толковый словарь ВРМ. 

До недавнего времени мы и для внутренней, и для внешней документации использовали xWiki. И если для внутренней документации ее применение оправдано, то для внешней xWiki не самое оптимальное решение: внешнюю документацию создают максимум два–три человека, регистрация дополнительных пользователей не нужна, на xWiki постоянно идут атаки спам-ботов, а изменение структуры документации, переименование, масс-правки, изменение оформления и некоторые другие вещи требуют или правок непосредственно в базе данных, или достаточно много телодвижений. Из плюсов — визуальный редактор, возможность импорта/экспорта статей в формате OpenDocument и гибкая настройка прав. Поэтому было решено для внешней клиентской документации переехать на новый движок, и выбор пал на Material for MkDocs.

Всем привет, меня зовут Мишинёва Екатерина, я – ведущий технический писатель с опытом работы в сфере IT уже практически 15 лет.

Сегодня я хочу поговорить о карьерных перспективах для технического писателя, которые я вывела для себя за время своей работы. Возможно, это будет полезно и вам. Делитесь своим мнением в комментариях!

Итак, начнем с того,  что технические писатели являются достаточно важными фигурами в IT-индустрии, они понятно и доступно представляют сложную информации. Для продвижения по карьерной лестнице техническому писателю требуется постоянное развитие компетенций.

Вот что я вывела для себя, в каких направлениях технический писатель может развивать свои навыки и компетенции:

Привет, Хабр! Я Владимир Хрыпун, руководитель центра компетенций по развитию BPM-систем в Первой грузовой компании. Сегодня разберем с вами, чем бизнес-аналитик отличается от системного и почему для проектов цифровой трансформации вам нужно два специалиста. Статья будет полезна менеджерам, продуктам, руководителям проекта. Всем кому надо объяснять, или кто сам хочет разобраться, в чем отличие бизнес и системных аналитиков. 

Часто всем участникам проекта хочется оптимизировать трудозатраты и бюджет. И очень светлая мысль, которая возникает у каждого второго продукта или РП: “А давайте у нас будет один аналитик, который сделает всё!”. У руководителей более высокого уровня, топов и собственников это идея возникает в 9 случаев из 10. В результате сроки сорваны, бюджет превысили в два раза. Почему так происходит и будет происходить разберем ниже. 

Основную идею этой статьи донесу через аналогию, а затем разберемся предметно. 

Представьте, вы участвуете в соревнованиях по многоборью. Надо преодолеть дистанцию за максимально короткое время. И вам как менеджеру команды можно набрать любое количество спортсменов, которое может позволить бюджет. Вы заранее знаете, какую местность надо преодолеть. Допустим, это будет, равнина, озеро и отвесная скала. 

С отвесной скалой все понятно. Точнее понятно, что ничего не понятно – нужны подготовленные спецы, которые быстро заберутся наверх и при этом не разобьются в лепешку. Поэтому профессионального скалолаза берем в команду 100%. А вот с равниной и озером не все однозначно – ведь плавать и бегать все умеют. Есть большой соблазн взять в команду одного спортсмена, а на сэкономленные деньги и время еще и интерфейс в синий покрасить. Вот так и формируются команды разработки, где есть выделенные разработчики (скалолазы) и аналитики (бизнес и системный анализ в одном флаконе). 

Привет, Хабр! На связи ведущий аналитик Ульяна. В первой главе я рассказала, что такое Confluence, зачем его используют и как работать с макросами. 

Во второй главе поговорим про шаблоны и метки, которые помогут организовать процессные и проектные рутины, например ведение MN, RFC и другое интересное.

Здравствуйте. В прошлой тематической (не касающейся биографических отступлений) публикации может я ничего особо интересного и не написал, впрочем - возможно я вообще ничего интересного не пишу, но у меня свой путь и прошу меня за это не судить - каждый имеет право выбора. Можно было-бы написать много чего интересного, но всё-же предпочитаю серии одной темы, от одного аккаунта, пока нет на портале функции нескольких галерей одного автора.

Не рассчитываю собрать много плюсов, рассчитываю собрать вычислительную машину своей архитектуры, с своей ОС и процессорами собственной архитектуры. Многие наверное задались-бы вопросом - в чём логика, когда IT отрасль так развита. Давайте посмотрим кому она развита..., хотя нет, скажу только что решил что будет так тогда, когда в общем-то думал как конвейеры своего GPU пристраивать к вычислительной машине, и хотел назвать конвейеры эти - препроцессорами. Проверил термин и обнаружил, что термин пропроцессор занят под название программы. Подумал - ну хорошо, раз одни уже называют чёрное белым, то самое время создавать другое пространство, где такой необходимости попробовать избежать и создать что-то такое, где граблей валяться под ногами будет поменьше.

Привет, я Егор Камелев, проектировщик интерфейсов (UX-дизайнер). За последние 20 лет я поработал с командами десятков агентств, IT-отделов, действующих проектов и продуктов, стартапов (и запущенных, и незавершённых). Я знаком с сотней команд, не меньше. И среди них не нашлось и двух, использующих одинаковые подходы к работе. Верно говорят: «У каждого додика — своя методика!».

У всех свои названия должностей, артефактов, процессов. Свои требования и наборы компетенций. Где-то проектированием занимается маркетолог и разработчик (потому что в команде больше никого и нету), а где-то эта задача распределена между десятью разными специалистами (системные- и бизнес-аналитики, технические писатели, UX-дизайнеры, продакт оунеры и так далее).

Поэтому в этой статье я не буду заявлять, что мой подход к работе — единственно верный. Он один из тысяч и в моём случае прекрасно работает: клиенты не заваливают меня правками, платят 100% предоплату и рекомендуют окружающим. Я распишу во всех деталях свой процесс предоставления услуги проектирования (создания интерактивного прототипа информационной системы на заказ). Уверен, что многим пригодятся мои знания. Погнали!

Документация к сложным библиотекам на питоне (напр. pandas) хранится в doc-строках и разбросана по сотням страниц сайта. В этой статье мы с помощью небольшого кода упакуем её (информацию из документации для каждого класса и метода) в... датайфрейм. Но зачем? Во-первых, это прикольно так её можно быстро искать и анализировать. Во-вторых, изучим некоторые встроенные питоновские средства работы с документацией. Наконец, такой датафрейм потенциально может стать основой для обучения/дообучения GPT-моделей писать более корректный, безошибочный, использующий всевозможные функции и их аргументы, код...

Настоящие знания остаются полезными гораздо дольше их носителей. Вопрос о том, как лучше хранить полезную информацию в электронном виде, всё ещё открыт.

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

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

Речь идёт о функциональных спецификациях к сайтам, приложениям и прочим информационным системам.

В начале карьеры UX-дизайнера я просто делал интерактивные прототипы, а документацию предпочитал не писать. Почему так:

Во-первых, сложно. Этому навыку никто не обучал, а написать 100 и более страниц текста по проекту — это как диссертацию накатать. Поэтому я говорил клиентам, что, мол, и так справитесь.

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

Продавать это было легко. Достаточно было рассказать о том, как я, заплатив несколько десятков тысяч за документ, экономил несколько сотен тысяч на разработке. И подкрепить рассказ конкретными цифрами и примерами. Чаще всего я рассказываю о том, как пожалел 50к на функциональную спецификацию на участок собственного проекта, и разработчики делали его два с половиной месяца вместо привычного одного. А месяц их работы обходился моей казне почти в 300к рублей. И если бы я не сэкономил на функциональной спецификации, то задача обошлась бы на 400к рублей дешевле.

Пусть вас не смущает надпись: «16+» в заголовке. В статье не будет ни слова о безудержном кутеже с куртизанками за игрой в блэк-джек.

Просто я решил очередной статьей отпраздновать выпуск в свет 16-й версии XWiki – «open-source аналога Confluence» (по мнению её разработчиков).

Сегодня мы сделаем шаблон спецификации API в XWiki, чтобы в будущем нам было легко и удобно его тиражировать. 

Статья скорее рассчитана на новичков, поэтому в процессе я немного расскажу об XWiki и наиболее простом способе её установки.

Привет, Хабр! Я Владимир Хрыпун, руководитель центра компетенций по развитию BPM-систем. Если кратко, то когда у вас в компании есть бизнес-процесс  регулярно повторяющиеся действия приводящие к нужным и прогнозируемым результатам, и вы хотите (или собственник бизнеса), чтобы эти результаты были лучше, потерь меньше и вообще все были счастливы и купили по ламбаргини, то вам нужна такая команда как наша. Мы помогаем частично или полностью автоматизировать бизнес-процессы компании. 

Эта статья о чек-листе анализа полноты бизнес-требований для проектов цифровой трансформации.

Чем больше людей работает в процессе, тем больше будет эффект от внедрения bpm-системы. Представим, что операционный бизнес – это грузоперевозки,  в бизнесе около 100 000 вагонов. У вас тысячи клиентов и сотни сотрудников. И допустим, что один из процессов – это согласование с клиентом маршрута, по которому пойдет груз. Результат: маршрут согласован, вагоны готовим под погрузку. В процессе участвует несколько отделов, выполняющих различные роли, и ежедневно сотрудники компании делают сотни действий, чтобы добиться результата – такие процессы называют сквозными, они большие, сложные, но жизненно важные для бизнеса. Экономические эффекты в таком проекте можно достичь упростив процесс, сложные или редко используемые шаги сделать понятными для сотрудников. Самый яркий пример – это “Вкусно и точка” *). Они не делают самые вкусные бургеры, зато они делают их быстро и с гарантированным уровнем качества. Сложные процессы упрощены и там, где это возможно, автоматизированы. Поэтому за 5 минут мы можем купить дешевый бургер, а компания на этом зарабатывает миллионы – все счастливы (особенно акционеры))). 

Привет, я Юля Зубова — руководитель отдела аналитики в диджитал-агентстве ДАЛЕЕ. Хотя написано много статей про роль аналитиков, открыты сотни вакансий и есть даже целые сформированные отделы, остались компании и команды, где их нет. Иногда приходится объяснять, зачем нужны эти специалисты.

Расскажу, какую роль играет аналитик, на каких проектах он жизненно необходим, а на каких можно обойтись и без него.

Темой поста на сегодня будет список конференций для аналитиков. Вообще, я продолжаю ежегодный обзор конференций для ИТ специалистов, просто как то так сложилось, что несколько лет назад я крайне заинтересовался конференциями, т.к. хотелось понять, что же там говорят различные эксперты, каковы новые технологические веяния, как работают успешные специалисты и начал понемногу собирать информацию из различных источников и как не странно, нормального источника - нет, но хотя бы есть какие то статьи в интернете! Большая часть материала, который я отсмотрел либо продажа собственной конференции и партнеров или проплаченную реклама, а так хочется понять куда сходить и не просто куда то, а на нормальное мероприятие, где высокий уровень докладов, классно продуманная организация мероприятия и необыкновенная неформальная часть.

Если у вас есть большая система, состоящая из множества микросервисов, то вы наверняка задавались вопросом: «Что сделать, чтобы архитектурная схема всей системы была всегда на 100% актуальной?».

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

Чтобы решить проблему мы автоматизировали отрисовку схем опираясь на метаданные IT-систем. Мы создали отдельный микросервис, который этим занимается и назвали его «Architect». О том как это происходит и как работает Architect я расскажу в этой статье, а также дам несколько советов, которые помогут внедрить то же самое у вас в компании.

Инструменты генерации контента с использованием искусственного интеллекта уже используются 52% бизнес-лидеров поддерживают контент-маркетинг — и это число продолжает расти. Неудивительно: эти инструменты обещают эффективность, скорость и удобство.

Но контенту, созданному ИИ, часто не хватает человеческого подхода, из-за чего он звучит скучно, отстраненно и лишено индивидуальности. Потерять свой бренд или голос писателя легко.

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

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

Краткий дайджест свежего контента и новой функциональности в документации YDB за декабрь прошлого года.

Привет, Хабр. Меня зовут Наталья Павликова, в YADRO я работаю в команде DocOps. У нас обширная инфраструктура вокруг задач документирования, которая немного напоминает ходячий замок Хаула. Сегодня я расскажу о небольшой ее части — процессе автоматической генерации и публикации документов из исходников кода.

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