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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Когда в коллегах согласья нет,
На лад проект их не пойдет,
И выйдет из него не profit, только cost.

Однажды Бэкендер, Фронтендер да Аналитик
Везти с тасками US взялись,
И вместе трое все в него впряглись;

Из кожи лезут вон, а US всё нет ходу!
Таски для них казались и легки:
Да Фронт рвется в Cloud-решения,
Бэк пятится назад, а Аналитик тянет в воду.

Кто виноват из них, кто прав, - судить не нам;
Да только UserStory и ныне там.

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

Так бывает, что в проектах, в которых я участвую, первоначальная оценка разработки проекта расходится с реальными сроками. И кажется, что уже всё сделали: внедрили скрам, планирование, ежедневные летучки, грумминг, внутри команды наладили коммуникацию, но всё равно раз за разом сроки разработки отодвигаются. 

И возникает закономерный вопрос — да что не так-то?

Docs as Сode — подход к работе с текстами, подразумевающий написание текста как кода:

• в простом текстовом редакторе или IDE;
• с использованием системы контроля версий;
• с CI / CD / Code Review.

В настоящее время Docs as Code широко применяется при работе с технической документацией, давая техническим писателям и проектным командам массу удобств и преимуществ.

Но что если пойти дальше, попробовать такой подход не с техническими, а с художественными текстами? Что если автор — не технарь и не айтишник? Просто юный начинающий писатель, который пробует писать прозу и стихи ручкой на бумаге, и надеется познакомить широкую публику со своим творчеством?

В этой статье я расскажу о таком эксперименте (забегая вперед, удачном). Моей дочери 11 лет, она пишет сказки, стихи и рассказы. Чтобы поддержать ее увлечение, я помог ей создать литературный сайт, используя подход Docs as Code. Она успешно освоила основы Markdown и Git. Сейчас она самостоятельно публикует новые произведения и обновляет новости на своем сайте https://lib-beliakova.github.io/.

Умный дядя по имени Дейл Карнеги писал, что имя человека - самый сладостный и самый важный для него звук на любом языке. Соответственно, лучший способ обидеть пользователя – исказить его имя в базе или не принять вводимое значение.

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

Мы подсчитали, что ручной ввод данных из типовых форм занимает 6–7 часов в день. Автономная система Smart Document Engine на смартфоне справляется с подобной задачей буквально за минуты. В этой статье мы расскажем о самых эффективных бизнес‑кейсах применения нашей мобильной OCR.

Привет, Хабр! Меня зовут Георгий Ржавин, работаю процессным архитектором в компании GlowByte, руковожу направлением Business Process Management. В этой статье хотел бы поделиться моим видением мирового рынка ПО (в первую очередь доступного в России) по моделированию и автоматизации процессов, а также рассказать о новых инструментах. Прежде всего материал будет интересен для бизнес‑ и процессных аналитиков.

К моим словам прошу относиться со здоровой долей скепсиса, ибо я не нейтив-спикер, а просто ИТшный переводчик-редактор (пусть даже и с 20-летним опытом).

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

Эту памятку или «дорожную карту» я опубликовал в своем телеграм-канале несколько месяцев назад, многократно её обкатал на проектах, и убедился в ее применимости — поэтому вешаю ниже.

Шагов в этой памятке 5: