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

Привет, Хабр! В 2020 году компания решила вывести на рынок линейку продуктов Platform V. Для них нужна была документация, которая на тот момент велась в Confluence. Нам предстояло проделать сложную и дорогую работу: собрать документы на нужные версии, привести тексты к единому стилю и терминологии, оформить как комплект документации от поставщика ПО. Расскажу, какие инструменты мы в СберТехе использовали, почему перешли от документирования в Confluence нa Docs-as-a-Code и создали инструмент Platform V GetDocs, который помогает эффективно писать документацию.

"Коллеги, пришлите сроки!" - повторял джун-аналитик в течение месяца...

Ситуация: 3 месяца назад, я, начинающий системный аналитик, пришла в монстрически крупную компанию. С первого дня меня кинули в рабочие задачи: напиши письма, протоколы, уточни сроки, откорректируй JSON-ку, попробуй написать требования... Задачи довольно простые, НО я понятия не имела, почему некоторые коллеги из смежных систем отвечают на мои письма за 1 день, в то время как другие просто игнорируют письма неделями.

У нас во «Фланте» инженеры работают еще и с технической документацией. При этом многие термины, например, относящиеся к Kubernetes, пишут по-разному: кто-то использует сленг, кто-то — латиницу, а кто-то — кириллицу. Чтобы навести порядок в терминологии, а заодно и исправлять опечатки, мы решили создать спелл-чекера и автоматизировать проверку орфографии.

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

Мировая статистика говорит, что английским владеет примерно 1,4 миллиарда человек, но носителей среди них всего 380 миллионов. То есть статистически семь из десяти читателей англоязычной документации — не носители языка.

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

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

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

Hola, Хабр! Я — технический писатель и за свою длинную карьеру в ИТ, нигде и никогда не сталкивался с ситуацией переизбытка в командах технических писателей. Наоборот, почти повсеместно в компаниях есть множество продуктов и проектов, в которых документация неполная, неточная, устаревшая и покрытая паутиной, а самих «техписов» хронически не хватает. Опытные спецы, умеющие читать код, документировать алгоритмы, описывать БД и API — это вообще люди уровня «ошибка выжившего». И, возможно, я нашел ответ на этот вопрос.

Мой первый on-call выдался нелегким. Недели тренингов и обучения не подготовили меня к тому что придется бегать по Slack каналам различных команд и искать того, кто может что либо знать о какой-то из частей системы. Оказалось что многие страницы в корпоративной Wiki уже не обновлялись несколько лет. Команды хранили свою документацию кто где хотел: кто в Wiki, кто в Google Docs, кто в GitHub и т.д. Наш on-call был не идеален: 2 человека выходили на дежурство 24/7. Один был ответственен за всю инфраструктуру (MySql, Cassandra, Kafka, ElasticSearch, Nomad и т.д.), второй же был Developer on-call и отвечал за все микросервисы и различные легаси системы, что в сумме давало около 300 различных сервисов от 7 команд на самых различных стеках и фреймворках (Java, Scala, Node, Go). Но что меня больше всего раздражало - так это невозможность быстро оценить на высшем уровне как проходит и обрабатывается запрос от пользователя. Диаграммы для разных бизнес частей точно также были либо устаревшими, либо без прилегающей документации, либо для какой-то бизнес логики не было ничего. И вот тогда мне пришла идея, что было бы неплохо иметь диаграммы, в которых можно не только нажать на любой элемент и добыть о нем более детальную информацию, но также получить ссылки на другие диаграммы и динамически их подгружать. Мне хотелось иметь возможность быстро разобраться в неизвестной распределенной системе, не переключаясь между диаграммой и документацией в Google Docs или Wiki. Именно так я начал работать над проектом Schem.io.

Предупреждение: в статье содержится большое количество GIF-изображений.

Наша команда Mobile Doc&Loc «Лаборатории Касперского» занимается подготовкой документации и локализации B2C-продуктов компании для мобильных устройств. Основная сложность (и одновременно фишка) нашей работы заключается в том, что необходимо регулярно подготавливать переводы на 34 языка в крайне сжатые сроки.

Меня зовут Юлиана Соломатина, я — Doc&Loc-инженер, и в этой статье я расскажу про инструменты-автоматизации, которые помогают нам справляться с наплывом задач и укладываться в дедлайны, не жертвуя при этом качеством. Кстати, многие из этих инструментов мы разработали сами.

Хотела начать текст с шутки про то, что раз инструкции никто не читает, то и писать их не обязательно. Однако 14 лет работы в IT-сфере доказывают, что это всё же довольно глупая шутка. В современных компаниях (не только в IT, но и особенно в IT!) на документации завязаны практически все процессы от проектирования ПО и ведения бэклога до эксплуатации и поддержки пользователей. Люди со стороны часто не догадываются, что в командах кроме суровых разработчиков, дотошных тестировщиков, внимательных сисадминов, осторожных безопасников и продвинутых девопсов трудятся технические писатели. Как правило, они одновременно суровые, дотошные, внимательные, осторожные и продвинутые, потому что именно на них лежит ответственность как за внутреннюю документацию, так и за корректные, грамотные, лаконичные и точные инструкции для пользователей. И писать желательно без девяти прилагательных в одном предложении, как строчкой выше 🙂

Сегодня поговорим об этих ребятах, о профессии, о людях в ней и о том, стоит ли войти в айти именно через вакансию техписа?

NB И да, обязательно читайте цитаты членов сообщества техписов — они рассказывают о самом актуальном в профессии из первых рук.

Компания у нас на full-remote, поэтому заседание кружка параноиков мы проводим как-то так. Иногда под банджо в углу.

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

Насчет бобров, я, кстати, не шутил. В Канаде они перегрызли кабель и оставили целый район Tumbler Ridge без оптоволоконной связи. Причем, животные, как мне кажется, делают все для того, чтобы внезапно лишить вас доступа к вашим ресурсам:

Макаки жуют провода. Цикады принимают кабели за ветки, и расковыривают их, чтобы отложить внутрь яйца. Акулы жуют трансатлантические кабели Google. А в топе источника проблем для крупной телекоммуникационной компании Level 3 Communications вообще были белки.

Короче, рано или поздно, кто-то обязательно что-то сломает, уронит, или зальет неверный конфиг в самый неподходящий момент. И вот тут появляется то, что отличает компании, которые успешно переживают фатальную аварию от тех, кто бегает кругами и пытается восстановить рассыпавшуюся инфраструктуру - DRP. Вот о том, как правильно написать Disaster Recovery Plan я сегодня вам и расскажу.

Салют! На связи Ганзюк Владимир. Тружусь инженером по нормативно-справочной информации (НСИ) в компании Bimeister.

Хочу поделиться с вами опытом работы с Excel: расскажу, как можно ускорить выполнение рутинных задач при работе с составлением наименований согласно нормативно-технической документации (НТД).

Приветствую, друзья! Меня зовут Александр Вихарев, и я работаю системным аналитиком в проектах для Fix Price. 

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

Чтобы избежать этого и освободить время специалистов компании, занимающихся сверкой документации, было решено разработать свою OCR-систему на основе решений внешних поставщиков. Технология OCR (optical character recognition, оптическое распознавание символов) позволяет извлекать текстовые слои из отсканированных документов для сверки и переводить их в удобные для работы форматы.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В какой-то определенный момент после старта нового проекта, когда «временный» MVP почти готов, весь интересный код уже написан, пакеты еще свежие и обновляются, команды начинают замедляться в Time to Market.

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

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

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

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

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

В этой статье я рассказала, как и зачем в Компании «Актив» мы делаем видеоинструкции на примере одного важного кейса: здесь про цели, сценарий, запись звука и программы для монтажа.

Должно быть интересно!