Всё о деятельности технических писателей
Все мы думаем, что хорошо говорим и пишем на своём родном русском языке. Не зря же в конце концов мы столько учились, да и в деловой переписке у нас всё вроде бы вполне неплохо. Но знаете ли вы о том, что даже для написания IT-документации есть свои правила? Поэтому сегодня в блоге ЛАНИТ на Хабре мы поделимся знаниями о русском «документном» языке.
Чтение ФТ — занятие непростое. Восприятие новой информации и её анализ требуют продолжительной концентрации и расходуют главный ресурс IT‑шника — внимание.
Если текст сложный, читатель спотыкается в нём и увязает, перечитывает по несколько раз, тратя время и ресурс внимания.
В статье расскажу про простые приёмы для начинающих писателей требований, которые помогут сделать их легче для чтения и ориентирования.
Привет, Хабр! Меня зовут Татьяна Шуравина, я системный аналитик Innovative People, работаю на проекте в банковском секторе. Вместе с командой оптимизируем и автоматизируем операции сотрудников банка для обслуживания юридических лиц. В своей первой статье я рассказывала, как стать системным аналитиком без специального образования. Сегодня хочу поделиться с теми, кто начал свой путь в аналитике, тонкостями магического процесса ведения проектной документации. Не для кого не секрет, что зачастую бывает такое, что система есть, а документации, чтобы понять, как она работает, нет. В статье расскажу, какие есть подходы к ведению документации, зачем это нужно и поделюсь практическим опытом.
Привет! Меня зовут Андрей Гладилин, я работаю в Swordfish Security над составлением технической документации для ИТ-решений. Нравится нам это или нет, но она сопровождает каждый этап разработки и эксплуатации ПО. Работая над десятками и сотнями описаний ежедневно, я отметил ряд особенностей и сделал полезные выводы. И здесь постарался разобрать все ключевые аспекты, влияющие на качество технической документации, и дать практические рекомендации по его повышению. Этот материал поможет техническим писателям, менеджерам и разработчикам создать документацию, которая точно будет работать.
Всем привет. Меня зовут Таня, я работаю системным аналитиком в МТС. В этой статье я расскажу о том, как писать документацию для разработки микросервисов.
Моя команда развивает несколько виджетов на главном экране мобильного финтех-приложения. Когда мы «пилим» новую фичу, как правило, мы разрабатываем под нее новый микросервис. Я, как системный аналитик команды, проектирую наш будущий сервис и пишу документацию для разработки. Так как почти каждая новая фича требует создания своего микросервиса, мне часто нужно писать под это дело документацию. Поэтому хочу поделиться с хабровчанами тем, как это делается у нас в команде.
В мире программной разработки, создание эффективной архитектуры является ключевым фактором для достижения успеха в проектах. Для этого необходимо использовать инструменты, которые позволят анализировать и определять взаимосвязи между компонентами системы, а также оценивать их влияние на стратегические цели. Интерес к языку Archimate, разработанному Open Group, в последние годы значительно возрос. Это связано с его универсальностью и простотой в использовании. Однако, одним из наиболее сложных аспектов языка является мотивационный слой, элементы которого часто остаются непонятными для начинающих пользователей. В данной статье мы рассмотрим, зачем нужен мотивационный слой в Archimate и как он может помочь в принятии правильных решений в области корпоративной архитектуры.
Привет, Хабр! Меня зовут Евгения Пономарева, я руководитель проектного офиса “Цифровых технологий”, ИТ-”дочки” ДОМ.РФ. В этой статье я расскажу о роли технической документации и роли технического писателя в IT-проектах ДОМ.РФ, а также поговорим о том, как построен процесс документирования в Институте развития, и как измерить качество документации.
«Цифровые технологии» занимаются развитием Единой информационной системы жилищного строительства (ЕИСЖС), привлечением клиентов, операционным сопровождением, а также созданием цифровых коммерческих сервисов, ориентированных на внешний рынок. Создание эффективных инструментов анализа рынка жилья, планирования и контроля его развития необходимо всем заинтересованным в цифровизации строительной отрасли. Отметим сразу, что под развитием мы подразумеваем разработку нового функционала и доработку используемого программного обеспечения.
Ни в форумах, ни в блогах, ни в России, ни в англоязычных ресурсах я не смог найти информацию о том, как логично упаковать всю релевантную фактуру в приятный технический документ. В книге М. Ильяхова «Пиши, сокращай» есть отдельная глава про дидактику, но там очень мало, вскользь и не совсем о том.
Еще есть ГОСТы 34 и 19 — там уже написано, из каких разделов должен состоять стандартизованный документ, но ведь кроме стандартизованных есть и другие документы — во всяком случае заказы на таковые ко мне приходили, — и каждый раз приходилось ломать голову.
Когда в коллегах согласья нет,
На лад проект их не пойдет,
И выйдет из него не profit, только cost.
Однажды Бэкендер, Фронтендер да Аналитик
Везти с тасками US взялись,
И вместе трое все в него впряглись;
Из кожи лезут вон, а US всё нет ходу!
Таски для них казались и легки:
Да Фронт рвется в Cloud-решения,
Бэк пятится назад, а Аналитик тянет в воду.
Кто виноват из них, кто прав, - судить не нам;
Да только UserStory и ныне там.
Уверен, многие узнали всем известную басню про трёх товарищей, которые пытаются затащить одну общую хотелку (некий воз). Только вот каждый тянет эту задачу в свою сторону, игнорируя усилия других. Сегодня я поделюсь с моими любимыми читателями примером, как сделать так, чтобы работа над задачей между тремя нашими героями шла дружно и эффективно.
Так бывает, что в проектах, в которых я участвую, первоначальная оценка разработки проекта расходится с реальными сроками. И кажется, что уже всё сделали: внедрили скрам, планирование, ежедневные летучки, грумминг, внутри команды наладили коммуникацию, но всё равно раз за разом сроки разработки отодвигаются.
И возникает закономерный вопрос — да что не так-то?
Docs as Сode — подход к работе с текстами, подразумевающий написание текста как кода:
В настоящее время 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:
Короткий ответ: потому что когда заказчики по прототипу получают оценку у разработчиков, они понимают, что не потянут разработку по деньгам.
Рассказ веду от лица основателя Проектората — бренда, объединившего самостоятельных проектировщиков/UX-дизайнеров.
Речь идёт исключительно о новых проектах, а не доработках в существующие. Самый распространённый сценарий выглядит так. Человек придумывает идею для своего продукта и решает его разработать. Он ищет по знакомым контакты программиста. Находит и в двух словах объясняет ему задачу. Программист тыкает пальцем в небо и называет стоимость разработки. Допустим, два миллиона. И намекает, что оценка примерная и было бы неплохо посмотреть на техническое задание.
Когда я пришла на новый проект, мне сказали, что миграция пройдёт в ближайшее время, и мне осталось «лишь» разобраться ней: огромная инфраструктура, множество систем и интеграций между ними, разнородные пользователи всевозможных масштабов с разными требованиями, целевые стратегии, бизнес задачи, множество команд развития и не одна линия поддержки, требования учета изменений законодательства и соблюдения стандартов безопасности, современные технологии, стремительное изменение мировой ситуации. Это всё, что меня окружает, и в чём надо разобраться.
При этом сложно понять структуру, найти какой-то единый документ, где можно было бы увидеть схему, как она есть сейчас и как это будет. Ввиду нехватки информации и сложности задачи, возникает ощущение безысходности и невозможности оценить верность решения с точки зрения проектируемой системы. Проект нужно начать делать сейчас, и находить способы распутывания текущего положения
Иногда казалось, что система очень хочет жить и намеренно меня запутывает. Моё стремление понять, с чем я имею дело и как это понять и подсветить какие-то подводные камни, риски, привело меня в замешательство, где я ни черта не понимаю, что происходит. Сложная задача требует нестандартных решений, и здесь возникает арт-терапия.