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

Привет! Меня зовут Елена Павлова, и более 10 лет я работаю в сфере IT. В этой статье расскажу, что помогает мне и моей команде создавать документацию, которую легко читать и понимать.

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

Несмотря на развитый ИТ-рынок в России, до сих пор не все понимают, что подразумевается под «аналитикой проекта» в заказной разработке. Разработчик пишет код, тестировщик проверяет корректность работы, а что делает аналитик проекта?

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

На протяжении всего моего времени работы с моделью и языком ArchiMate от The Open Group, внимательно наблюдая за практиками сообщества, я не переставал удивляться тому, насколько мало используются “точки зрения” (viewpoint’ы), предложенные в ArchiMate 2.1.

Я открыл их для себя благодаря отличному бесплатному опенсорсному решению Archi, разработанному Филлипом Бовуаром (Phillip Beauvoir), которое очень грамотно раскрывает потенциал представлений (view) в помощи заинтересованным сторонам, желающими создать всеобъемлющую модель архитектуры рассматриваемых ими организаций.

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

Я считаю, что понимать и уметь применять точки зрения так же важно, как и разбираться во всех остальных 60 (или около того) конструкциях языка ArchiMate.

"И всё равно, посреди всей этой тьмы, я вижу людей, которые не ломаются, я вижу людей, которые не сдаются. Даже зная, что надежда утрачена. И понимают, что от утраты до обретения, на самом деле, всего один шаг…"

Привет, Хабр! Меня зовут Вячеслав Смирнов, я руковожу техническими писателями в Platform V Pangolin. Три года назад я пришел в продукт в качестве DBA, а спустя год организовал команду техписов и стал разрабатывать документацию.

Давным-давно команда Pangolin состояла из 15-20 человек. Документация по продукту была в зачаточном состоянии. Разработчики сами пилили фичи и сами же их описывали. Но потом Pangolin вырос, вышел на внешний рынок и нам стали нужны профессиональные технические писатели.

А мир техписов разнообразен: здесь есть и редакторы-корректоры, и технари, умеющие развернуть дистрибутив. Техписы без технического опыта не всегда готовы разбираться в сложном продукте. Но, как выяснилось на практике, и технарям, пришедшим в команду, не хватало погружения в тему СУБД, чтобы писать документацию. Попробовав разные варианты, мы нашли для себя такой выход: наши техписы обязательно проходят базовые курсы DBA, и мы берем в команду не только техписов, но и DBA, желающих писать доку.

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

Привет! Меня зовут Дмитрий. Я архитектор решений в крупной российской компании, более 15 лет проектирую, пишу код и руковожу командами. Сотрудничаю с Практикумом как ревьюер курса по Java и как автор курса «Архитектура программного обеспечения» в Яндекс Практикуме.

Предположим, вы решили развлечься дизайном систем (System design), пусть даже и не добровольно, на собеседовании. Если компания поленилась поделиться рабочим контекстом, то задача может быть в формате «запроектируй Твиттер». Более кандидатоориентированная компания N может попросить «спроектируй поиск на сервисе N».

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

Привет, меня зовут Ольга Громыко. Я работаю техническим писателем в R‑Style Softlab и создаю документацию по банковскому ПО, которая помогает пользователям разобраться в работе сервисов. В статье подробно расскажу, чем занимается технический писатель, какие навыки помогают ему в работе и какие перспективы есть у таких специалистов.

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

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

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

Для начала хотелось бы в двух словах рассказать о том, что это вообще за профессия такая. Если вкратце, то технический писатель - это сотрудник, который занимается написанием технической документации.

Писатели могут заниматься написанием следующих типов документации:

В пятницу ко мне подошел коллега и с гордостью показал новую утилиту, которую он разработал. Она генерирует документацию в Markdown на основе .env файла, включая переменные, их значения и комментарии. Я, конечно, поздравил коллегу с успехом и попросил посмотреть на результат. И тут меня ждал шок — таблица в Markdown! Вы только представьте себе это!

Так начался холивар...

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

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

На связи техредакция RuStore. В прошлой статье мы рассказали о миграции документации RuStore. Мы продолжаем исследовать возможности Docusaurus и знакомить вас с ними. Сегодня расскажем о способах настройки навигационного меню и о том, почему мы выбрали автоматический режим.

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

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

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

Упростить этот процесс можно с помощью специальных пакетов программ, таких как SolidWorks Composer. Однако они имеют свои недостатки, в частности, платное использование и необходимость значительной переработки иллюстраций при изменении модели.

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

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

Привет, Хабр! Меня зовут Саша Новицкая, я ведущий дизайнер продукта в Х5 Tech. Занимаюсь B2B продуктами и дизайн-системой. Хочу рассказать о том, как мы вместе с техническими писателями разрабатывали и дорабатывали наш ToV (Tone of Voice). И даже поделимся результатом нашей работы в виде гайда. А помогать мне в этом будет мой соавтор и менеджер направления «Разработки технической документации» Х5 Tech Настя Московкина.

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

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

Например, две разные команды обнаруживают, что занимаются решением одной задачи. С кем не бывает! Или уходит сотрудник, а с ним уходят и все знания об одной из систем. Или классные идеи бесконечно откладываются на потом, потому что сталкиваются со сложностями в реализации. 

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

Меня зовут Саша Камзеева, я руководитель системного анализа в Lamoda Tech. На протяжении 8 лет помогаю создавать и поддерживать базы знаний в компании. В этой статье я перечислю проблемы в базе знаний, которые отражаются на организационных процессах, и расскажу, как искать решение этих проблем. 

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

Привет, Хабр! Это Евгения Миронова — Senior Business Analyst, Павел Орлов — Senior System Analyst и Мансур Сафиуллин — Middle Business Analyst из МТС Диджитал. Сегодня будем говорить о проектной документации — той самой, в которой так часто «черт ногу сломит». Чтобы читать было интереснее, мы дополнили теорию практическими советами. Но не спешите их тестировать — сначала дочитайте пост до конца. Поехали!

Привет! Это Маша, технический писатель в группе документации Ozon. Мы делаем внутреннюю документацию в департаменте «Поиск, рекомендации, реклама», в который входит 40 команд разработки. Наш департамент постоянно развивается, появляются новые команды и люди, которым нужно побыстрее влиться в компанию и коллектив. Недавно одна из команд планировала набирать новых сотрудников, и коллеги попросили помочь сделать приветственную страницу для новичков — онбординг.

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

Привет! Меня зовут Илья и я занимаюсь систематизацией информационных ресурсов.

Конечно, каждая отрасль имеет право на свои особенности, но на красоту можно и нужно влиять. Эти размышления относятся к описанию ИТ‑продуктов, где наглядность is a must. Дело не в квалификации читателя — информации стало слишком много и она постоянно обновляется.

Работая с менеджерами в сфере ИТ, обнаружил, что часто отсутствует системное представление о видах инфраструктуры, которая необходима для развертывания автоматизированных систем (АС). Вследствие этого возникают ошибки в планировании разработки и развертывания АС — некоторые виды инфраструктуры упускаются из внимания: не учитываются в проектах, не запрашиваются технические условия, не согласовывается использование, отсутствуют договоры на использование нужной инфраструктуры и т. п. Также возникают ошибки в распределении ответственности при эксплуатации развернутой АС, когда часть инфраструктуры оказывается «ничейной», потому что о ее обслуживании забыли договориться.

Для того, чтобы облегчить жизнь специалистам, с которыми приходилось работать, я создал простую иерархическую диаграмму, которой хотел бы поделиться с общественностью. Она хороша для учебных целей или для быстрой оценки проекта. Диаграмма показана на Рисунке 1. Данная диаграмма наглядно представляет, какие виды инфраструктур существуют, и дает разбивку АС на 5 типов, в зависимости от используемых видов инфраструктуры.

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

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

Меня зовут Катя Назмеева, сейчас я тестирую бэк в Lamoda Tech. В статье я предложу стратегии для успешного проведения интеграционного тестирования микросервисов и расскажу про инструменты, которые могут облегчить этот процесс. Обсудим, как организовать все таким образом, чтобы интеграционное тестирование не создавало задержек в новых релизах — и не заставляло QA страдать.

Привет, друзья-аналитики!

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