Всё о деятельности технических писателей
Привет, друзья-аналитики!
Хочу поговорить об отрасли, с которой начинался мой путь в аналитике и которая до сих пор занимает особое место в моем сердце — ритейл. Аналитикам в этой области будет полезно, для остальных интересно почитать. Статья направлена на базовую аналитику, в следующих статьях будем погружаться глубже.
Введение
Представление моделей бизнес‑процессов на основе онтологий (онтологическое моделирование) эквивалентно Semantic BPM. Введение в семантический BPM (Business Process Management) см. «Semantic BPM. Семантика и синтаксис бизнес‑процессов» [semBPM24]. Если кратко, то можно провести аналогию: если классическая BPM система (BPMS: ARIS, бизнес‑студия, fox‑manager и т. п.) — это технологический аналог mediawiki (wikipedia), то Semantic BPM — это технологический аналог semantic mediaWiki (Wikidata), т. е.
IF MediaWiki → Semantic MediaWiki then BPM (ARIS, BPMS, EA) → Semantic BPM
Основной замысел (цель) семантического представления процессов (BPM, EA) не классическими BPM‑системами, а семантическими (Linked Data) — такой же, как и у семантических wiki
Одно из ключевых дополнений к wiki‑гиперссылки (html) это указание не просто что «ОбъектА связан с ОбъектомБ» (т. е. просто «связано») и соответствующий кликабельный переход (wiki‑ссылки, markdown syntax), а указание, что «ОбъектА связан с ОбъектомБ» такими‑то типом отношения (впрочем, как и задание других свойств объекта через отношения).
Изначально все BPMS (изначально называемые CASE‑средствами) — семантические, т.к. их суть — это отношения между объектами, только в них семантика глубоко спрятана «под капотом» BPMS и нестандартная (собственная, проприетарная). Semantic BPM «поднимает» семантическую составляющую на поверхность (возможность работы с семантическим слоем) и использует стандартные сематические технологии Linked Data.
В основе RDF (Resource Description Framework) — триплеты «субъект — отношение — объект» лежит ERD: Entity Relationship (ER) diagram. RDF \ ERD — это способ формализации знаний на основе атома знания — триплета. Вообще ER, subject, predicate, типы рассуждений и другие базовые элементы для работы со знаниями в СССР содержались в школьных учебниках [Логика54].
Слышали фразу: «Нет тз — результат хз»? А ведь в нем столько правды! Правильно составленное техническое задание помогает избежать недоразумений между заказчиком и разработчиком, чтобы на выходе проект получился таким, как вы планировали в самом начале.
В этой статье мы подробно рассмотрим шаги по созданию ТЗ и что необходимо учитывать на каждом этапе. Придерживаясь нашего плана составления ТЗ, вы сможете четко описать свои ожидания и требования, чтобы подрядчик понял вас.
Влияет ли наше состояние на то как мы думаем и что говорим? Как через состояние и мышление повысить качество документации?
Приветствую всех! Меня зовут Катя Фролова, я работаю техническим писателем в RuStore.
В прошлом году документация RuStore переехала на новый движок.
Расскажу, почему мы отказались от хорошего решения ради более хорошего и чего нам это стоило.
Всем привет. Меня зовут Татьяна Цикунова, я работаю системным аналитиком в компании МойСклад, в команде eCommerce. Моя команда специализируется на разработке интеграций сайтов с сервисом МойСклад. Мы помогаем бизнесу автоматизировать процессы: учета, продаж, коммуникаций с клиентами, выход на новые торговые площадки. Также мы разрабатываем интеграции с самыми популярными маркетплейсами на рынке России и зарубежных стран У МоегоСклада уже есть решения для селлеров на Ozon, Wildberries, Яндекс Маркете и Мегамаркете, а также для зарубежных маркетплейсов.
В статье я расскажу о том, что такое эти самые интеграции с маркетплейсами на примере сравнения наших решений для Ozon и Wildberries.
Сначала приведу немного статистики от Data Insight. Чтобы понимать, насколько сейчас популярна торговля на маркетплейсах, достаточно взглянуть на слайды ниже.
Как за 2 месяца создать самопополняемую документацию там, где ее никогда не было? Вот четыре этапа, которые нужно будет пройти техническому писателю.
Привет, Хабр! Меня зовут Виктория Юльская, и я старший системный аналитик в Ozon.
Я думаю, здесь найдётся много людей, которые хоть раз работали с документацией API в Confluence. Да-да, те самые километровые страницы на каждый метод — с описанием всего и вся в виде текста, таблиц, диаграмм последовательности и т. д.
Зачастую такая документация API в Confluence устаревает ровно в тот момент, как её закончили писать. После передачи задачи в разработку, как только что-то непонятно, куда все идут? Правильно, к аналитику — «А как это работает? А что это значит? А что если...?».
Ну вот же дока, там все написано... но обычно никто не хочет читать огромную доку на метод, быстрее же спросить. И зачастую у самих аналитиков есть вопросики по актуальности этой документации (уже есть новые договорённости со встреч, комментарии в документации и т. д.).
Есть ли более эффективный способ ведения и поддержания документации API в актуальном состоянии? Давайте разбираться.
Что такое Docs as Code классно описано в статье Docs as Code: введение в предмет.
В двух словах: это ведение документации на языке разметки (Markdown, AsciiDoc) с хранением в репозитории.
Плюшки — все вытекающие от работы с репозиторием.
Минусы — в этой статье.
На осенних Analyst Days прошлого года добрая четверть докладов была посвящена теме Docs as Code. На тот момент конклав аналитиков на моём прежнем месте работы уже 9 месяцев решал, нужен ли на проекте модный-стильный-молодёжный Docs as Code или всё же остаться в дышащем на ладан Confluence. К чему пришли — не знаю. На новом месте работы мы внедрили Docs as Code за неделю — было чёткое понимание проблематики, подход казался выигрышным решением. Используем полгода.
Без толковой API-документации сложно делать открытый продукт и ждать, что его будут развивать пользователи. Часто владельцы сервисов занимаются документацией по остаточному принципу. В итоге разработчику достаётся запутанная инструкция, а интеграция усложняется или просто становится невозможной.
Мы осознали эту проблему до разработки открытого API и заранее спланировали, как сделать документацию понятной. Сегодня расскажу подробно про портал документации Alfa API. Как с ним быстро разобраться в технической реализации, а главное — улучшить впечатления от работы со сложным продуктом — узнаете в статье.
У химиков есть известная байка, которую они любят рассказывать молодому поколению. Главный герой этой истории — студент, который пошагово воспроизводил методику одного химического эксперимента из учебника. Он старательно выполнил очередной шаг «добавьте азотную кислоту» и... в лаборатории прогремел взрыв! Когда впоследствии стали разбираться, в чём же дело, выяснилось, что на следующей странице учебника было написано: «... медленно, по каплям».
Примечания и уточнения — очень важный элемент любого технического и научного текста. В любом документе фрагменты текста можно ранжировать по важности и критичности излагаемых сведений. Бывает просто обычный текст, который течёт себе ровно, как спокойная равнинная река. Бывают фрагменты с дополнительной, необязательной, уточняющей информацией: автору хотелось их добавить в текст, но они плохо укладываются в основную логику изложения материала. А ещё бывают критичные замечания и уточнения, которые обязательно должны быть обвешаны мигающими сигнальными огнями, сиренами, хлопушками и прочими средствами привлечения внимания читателя.
Как же лучше писать и оформлять примечания в технических текстах?
В статье расскажу про Foliant и про возможности по документированию HTTP API с его использованием. Упор сделаю на API, которые описываются с помощью OpenAPI/Swagger. Также вскользь коснусь возможностей по документированию API, описанных с помощью других спецификаций.
Привет техписам и всему ИТ-сообществу. На связи команда «Инферит Клаудмастер», и мы хотим рассказать вам о том, как мы организовали базу знаний о нашем продукте. Для этого мы поговорили с Миленой Балановой, техническим писателем Инферит Клаудмастер, которая в перерывах между «витанием в виртуальных облаках» и написанием документации рада поделиться инсайтами о создании базы знаний:
«Ваша документация — отстой!», «Я её никогда не читаю, всё равно там ерунда написана!», «Эти документаторы опять всё напутали», «Да любая нейросеть быстро напишет это в сто раз лучше», «Там никогда не найти ничего нужного», «А разве у нас есть документация?»
Обратная связь от читателей-пользователей далеко не всегда бывает конструктивной и вдохновляющей. Почему же так получается? Давайте разберём пять основных претензий читателей к технической документации и подумаем, что со всем этим делать.
C вами Семён Факторович и компания documentat.io. С 2018 года мы помогаем IT-компаниям создавать техническую документацию: пишем документацию на заказ, консультируем инженерные команды по процессам документирования, учим техписателей и инженеров писать документацию.
В январе 2024 года мы провели большой социологический опрос среди техписателей и других IT-специалистов, разрабатывающих документацию. В этой серии статей я делюсь результатами нашего опроса.
В прошлой статье я рассказал о географии и демографии русскоязычных техписателей, а также рассмотрел зарплатную статистику в техписательском сообществе РФ.
В этой статье я расскажу об индустриях, в которых работают русскоязычные техписатели, о видах документов, которые они разрабатывают, о востребованности знаний ГОСТ и о том, как всё это влияет на техписательские зарплаты.
Всем привет, меня зовут Влад и я запилил собственный IT стартап в одиночку потратив $100. Я давно хотел проверить свои силы и показать самому себе на что я способен, смогу ли я дойти от: создания идеи, проработки ui/ux, разработки frontend & backend, до публикации продукта и его маркетинга.
Для общего понимания я постараюсь кратко описать свой background. В 14 лет я увлёкся веб разработкой поскольку у меня была команда по игре counter strike и для того чтобы заявляться на турниры, нам требовался сайт, по мере его поддержания, я освоил исскуство владения фотошопом. Этот сайт я начал монетезировать и смотрел как его можно продвигать.
Дальше был универ, где я много писал код на c++, python, c#, писал свои нейронки, программировал роботов, проходил алгоритмы и структуры данных. В это самое время вместе с друзьями начали развивать ивент стартап, который помогал пользователям узнавать расписание, изменения, следить за интересными спикерами. Я занимался ui/ux проектированием и frontend разработкой. В это самое время я изучил первые в своей жизни методологии дизайна: google material design guidelines and Apple Human Interface Guidelines.
Писал диплом на тему: примерка мебели в дополненой реальности на свифте.
Потом был момент, когда мы с партнёрами открыли it outsource компанию на 40 человек разработки, где я был CTO и следил за технологиями в компании на стеке: JS, Typescript, React, Vue, Php, python, nodejs, reactnative.
И весь свой накопленный опыт я хотел применить для создания продукта.
Привет, Хабр! Меня зовут Кирилл Рупасов. Я руковожу группой инженеров SOC (Security Operations Center) в «К2 Кибербезопасность». Я не понаслышке знаю, как порой непросто создавать контент для Центра мониторинга кибербезопасности. Написать одно правило обычно несложно, а вот разработать их связанный комплекс — задача достаточно трудная, особенно для молодых команд.
Под катом я собрал всю полезную информацию о грамотном создании контента: виды правил и их нюансы, workflow и возможные проблемы, сценарии обработки инцидентов. А также рассказал, как мы организовали процесс разработки и поддержки актуальности контента в своем коммерческом SOC.
Хабр, привет!
Меня расстраивает несправедливость в мире IT: для новичков-разработчиков есть куча пошаговых инструкций, о там, как разработать API или мобильное приложение. Хочу немного уровнять баланс вселенной, поэтому я написал небольшой гайд для аналитиков для составления документации.
В прошлой статье я представил шаблон, а теперь заполнил его для фичи «Экспресс-доставка товара в маркетплейсе». Моя цель – показать, как можно вести документацию и как правильно заполнять этот шаблон.
В статье собраны рекомендации по подготовке текста к машинному переводу на основе советов IBM (Machine translation tips, вебархив). Они помогут оптимизировать процесс перевода и сократить время на постредактирование.
При адаптации текста к автопереводу на разные языки необходимо уделить внимание стилистике, грамматике, терминологии, пунктуации, орфографии и верстке. Просторечия, неполные предложения, неправильная пунктуация, многозначные слова приведут к ошибкам в переводе. Обо всем подробнее.
C вами Семён Факторович и компания documentat.io. С 2018 года мы помогаем IT-компаниям создавать техническую документацию: пишем документацию на заказ, консультируем инженерные команды по процессам документирования, учим техписателей и инженеров писать документацию.
В январе 2024 года мы провели большой опрос среди техписателей и других IT-специалистов, разрабатывающих документацию. Теперь я начинаю серию статей, в которой поделюсь с вами результатами опроса.
В первой статье я расскажу о географии и демографии русскоязычных техписателей — где мы живём, сколько нам лет, каков наш гендерный состав — а также рассмотрю зарплатную статистику в техписательском сообществе РФ.