Как стать автором
Обновить
21.35

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

Всё о деятельности технических писателей

Сначала показывать
Порог рейтинга
Уровень сложности

Manipulation Process Efficiency (MPE) Benchmark

Время на прочтение1 мин
Количество просмотров447

Бенчмарк эффективности решения задач манипуляции предметами (MPE)

Назначение: Бенчмарк предназначен для оценки эффективности применения робототехнического комплекса в практических задачах манипуляции предметами по сравнению с другими системами автоматизации (в т.ч. роботизации) или использованием ручного человеческого труда.

Разработано: Лаборатория робототехники Сбера

Внимание! Если вы перешли сюда по ссылке из поисковой системы!

Корректная ссылка на статью: https://habr.com/ru/post/534954/

Читать далее

Тернистый путь стандартизации блокчейн технологий в России

Время на прочтение10 мин
Количество просмотров3.1K

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

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

Но как этого достичь? В коммерческой среде, когда нужно наладить взаимодействие участников какого-либо сектора экономики, создаются ассоциации и консорциумы. В чисто технологических вопросах такими площадками выступают центры стандартизации, например МСЭ-Т(ITU-T), ИСО (Международная организация по стандартизации). В России такой независимой площадкой объединения экспертов блокчейн-технологий выступает Технический Комитет по стандартизации "Программно-аппаратные средства технологий распределённого реестра и блокчейн" (http://bccmt.ru).

Как руководитель одной из рабочих групп (с декабря 2019 года) и эксперт ISO TC 307 DLT (TC 307 - Blockchain and distributed ledger technologies) я хочу поделиться информацией по стандартизации блокчейн технологий в России и мире. А также привлечь внимание экспертов блокчейн рынка к работе ТК 159, как площадке взаимодействия, которая может многое дать своим участникам.

Узнать больше

Генератор диаграмм таблиц ClickHouse для PlantUML

Время на прочтение4 мин
Количество просмотров4.8K

Когда появляется необходимость документировать схемы баз данных, разные DBMS предоставляют свои инструменты для подобных задач. И большинство из них поддерживает DESC table_name, в том числе и ClickHouse. Однако, результат этой команды не столь выразителен, как хотелось бы.


DESCRIBE TABLE data_lr

name        type      default_type   default_expression   comment   codec_expression   ttl_expression
Path        String                                                  ZSTD(3)
Value       Float64                                                 Gorilla, LZ4
Time        UInt32                                                  DoubleDelta, LZ4
Date        Date                                                    DoubleDelta, LZ4
Timestamp   UInt32                                                  DoubleDelta, LZ4

При этом, системные таблицы tables и columns содержат исчерпывающую информацию, объединив которую, можно получить вот такой симпатичный результат:


Читать дальше →

Как сделать текст легче

Время на прочтение6 мин
Количество просмотров5.4K

В прошлой статье я обещала, что расскажу, как сделать документы легче для восприятия. Есть два основных направления: текстовка и структура документа. Сегодня поработаем с текстами. Технические документы на русском читаются особенно тяжело, и добиться легкости в них сложнее, чем в английском. Как можно исправить многословные, громоздкие документы? Давайте попробуем сделать их конкретнее, проще, короче, и последовательнее.

Читать дальше →

Истории

Такие разные документы: конструкторские vs. user-oriented

Время на прочтение3 мин
Количество просмотров2.2K
Моим любимым русским техническим писателям посвящается

Работа технического писателя – создавать документы на программные продукты, в основном всевозможные руководства пользователя. Разработка документа – дело непростое. Есть очень много подходов и практик. Например, технические писатели в научно-производственных предприятиях часто пишут по ГОСТам или другим отечественным стандартам. Их цель – точно и верно описать продукт. А technical writers в международных компаниях пишут по style guides (Microsoft Manual of Style, например). В этом случае цель, скорее, донести до пользователя, как продукт работает. Здесь фокус смещен с продукта на читателя.

Мне довелось побыть техническим писателем в разных местах, с разными правилами и политиками. Оглядываясь назад, могу сказать, что даже в НИИ тексты можно переориентировать на конечного пользователя, и документы от этого выиграют. Но в ГОСТах про это не пишут. А style guides, во-первых, на английском, а во-вторых, не афишируются в отечественных конторах типа НПП, КБ, и пр. Поэтому есть явная нехватка информации. Я попробую ее восполнить.
Читать дальше →

Рабочие места Selectel: тестировщик интерфейсов, технический писатель, менеджер продуктов, тестировщик и редакторы

Время на прочтение11 мин
Количество просмотров11K

Привет, Хабр! Сегодняшняя статья целиком посвящена рабочим местам и уголкам для хобби сотрудников Selectel. Всегда было интересно читать похожие посты других компаний, включая сам Habr. И мы решили поделиться своей историей. Если у вас будут вопросы, задавайте в комментариях, ответим. Кстати, если есть желание, хвастайтесь в комментариях своими рабочими местами, хобби или DIY-проектами.
Читать дальше →

Проектные решения: игра по твоим правилам

Время на прочтение27 мин
Количество просмотров26K
Не секрет, что чем крупнее программный проект, тем больше его успех зависит от результатов работы аналитиков, в частности, от выбора правильной стратегии составления и согласования проектных решений. Однако как организовать работу этих творческих сотрудников? И как сделать так, чтобы результаты их деятельности были одинаково понятны как  представителям заказчика, так и программистам? Как оценить возможные сроки выполнения и значимость этой работы для проекта? В этой статье я попытался сформулировать свои рецепты оптимизации управления аналитической работой на проектах по созданию программного обеспечения для государственных заказчиков. Приветствуется любая критика.

Источник
Читать дальше →

Вебкаст Хабр ПРО #5. Техноавтор: эксперт vs писатель

Время на прочтение2 мин
Количество просмотров2.3K


Водка и шампанское, огонь и лёд, физика и лирика, экспертиза и нарратив — любой технический автор попадает на территорию, где сталкиваются два противоположных направления: техническое и литературное. Как сильно они конфликтуют? Где начинаются и где заканчиваются их границы? Как найти нужный баланс между этими направлениями и написать крутой технический текст, который может выиграть конкурс? Обо всём этом мы решили поговорить с тремя опытными хабраавторами и вместе с нашими партнёрами из SBTG.ru организовали для них творческий вечер, где они расскажут о том, как надо создавать статьи для Хабра. Подробности — под катом.

Как мы в «Активе» пишем пользовательскую документацию. Почему это важно

Время на прочтение5 мин
Количество просмотров6.3K

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


Читать дальше →

Как вести технический блог?

Время на прочтение16 мин
Количество просмотров21K


Я работаю в коммерческой разработке с 2011 года. С конца 2012 занимаюсь разработкой под iOS. Свою первую техническую статью я написал на Хабре в начале 2017 года про подход к локализации мобильных приложений. Потом выпустил ещё несколько статей по iOS-разработке на Хабре и в конце 2017 года я перешёл в новую компанию и решил вести блог про solution architecture https://medium.com/@nvashanin, где начал описывать общие концепты, обязанности архитектора, его скилл-сет и т.д. К лету 2020 года количество просмотров моих статей перевалило за 800 тысяч, а количество времени, которое люди потратили на прочтение — больше 6 млн минут, или около 12 лет чистого времени. Флагманская статья была переведена другими людьми на разные языки: например, польский или испанский.

В статье я расскажу про свой путь к техническому блогу — от идеи до регулярных публикаций. Расскажу, о чём можно писать, как писать и как оформлять статьи, а также о том, как на них заработать. Мне, например, удалось купить себе часы на деньги, которые принёс блог. Статья подойдёт тем, кто только задумывается о написании статей, а также будет полезна и тем, кто уже активно пишет.
Читать дальше →

Техническая документация в разработке ПО: кто, зачем, когда и как описывает проект

Время на прочтение6 мин
Количество просмотров81K
image

Привет! Меня зовут Даша Григорьева, я технический писатель в компании 65apps. Мы занимаемся разработкой сложных мобильных решений, и моя задача — подготовка технической документации по проектам. Очень часто роль технического писателя бывает недооцененной в компании (не у нас, конечно). Поэтому я хочу рассказать, зачем компании-разработчику нужен такой специалист, что такое технический проект, чем он отличается от ТЗ и почему это все необходимо для разработки мобильного приложения.
Читать дальше →

Как снять обучающий видеоролик: 10 секретов технического писателя

Время на прочтение13 мин
Количество просмотров15K
Я – технический писатель, 4 года снимаю обучающие видеоролики для системы Directum RX. В беседе со мной коллеги часто слышат:

  • «К ролику пришли замечания»;
  • «Дай, пожалуйста, доступ к роликам»;
  • «Любовь к роликам» и тому подобное.

Наверное, в их головах рисуются примерно такие картинки:

image

Docs as code против или вместе с Confluence? Обзор нескольких способов публикации из репозитория в Confluence

Время на прочтение7 мин
Количество просмотров15K
Многие уже давно или активно используют или смотрят в сторону модели хранения и публикации документации как кода, это значит применять к документации все те же правила, инструменты и процедуры, что и к программному коду, например, хранить в репозитории, прогонять тесты, собирать и релизить в CI/CD. Этот подход позволяет поддерживать документацию актуальной к коду, версионировать и отслеживать изменения, используя привычные инструменты разработки.

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

Ближайшие события

25 – 26 апреля
IT-конференция Merge Tatarstan 2025
Казань

Как оживить документацию?

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



На web-проектах Альфа-Банка используется фреймворк для автоматизации тестирования Akita, который использует для BDD-сценарии. К настоящему моменту фреймворк набрал большую популярность благодаря низкому порогу входа, удобству использования и возможности тестировать верстку. Но мы решили пойти дальше — на основе описанных тестовых сценариев формировать документацию, тем самым сильно сокращая время которое аналитики тратят на на извечную проблему актуализации документации.

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

  • скриншоты;
  • значения переменных (config File, учетные записи пользователей и т.д.);
  • статусы и параметры запросов.

Мы посмотрели на наш существующий плагин, который был, по сути, статическим анализатором и формировал документацию на основе описанных в .feature-файлах сценариев. Решили добавить динамики, и для того, чтобы не городить плагин над плагином, приняли решение написать свой собственный.
Читать дальше →

Немного технической лирики о C++ Tools от JetBrains, и при чем тут единороги

Время на прочтение4 мин
Количество просмотров9.1K
Начну не с моего типичного “Привет, Хабр! У нас тут очередной крутой релиз”, а с “Привет, меня зовут Настя, я ПММ в JetBrains и я отвечаю за наши инструменты для C++”. Или нет, попробую еще раз, вот так: “Привет, пишет вам C++ разработчик с 8-летним стажем, который 5 лет назад нашел-таки себе применение в любимой и знакомой компании мечты – JetBrains, а потом в сутках внезапно закончились часы, а идеи всё прут”.

Нет, это не традиционный пост о поисках кандидатов на вакансию. Я попытаюсь рассказать про то, почему инструментов для C++ у нас несколько и какие есть идеи и планы у нас на их счет, а еще почему вы не забудете C++, если перестанете писать на нем как разработчик, а станете PMM-ом (спойлер, если вы не член комитета стандартизации языка C++, то у вас большие шансы узнать язык даже лучше). А если после этого вам захочется поучаствовать в этом в роли PMM-а, то я буду рада вашим резюме на anastasia.kazakova@jetbrains.com.
Читать дальше →

Как мы считаем метрики разработки и поддержки документации. Доклад Яндекса

Время на прочтение6 мин
Количество просмотров8.3K

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



Рассказывает Юрий Никулин, руководитель службы разработки технической документации.


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


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


Как «снести» вашу документацию и начать жить

Время на прочтение13 мин
Количество просмотров10K
Сегодня поговорим о том, как избавиться от документации, которая не работает, описывает какое-то легаси, не организована, не соответствует идентичности вашего бренда, да что там — просто плохой документации. Чтобы затем подготовить и реорганизовать хорошую, валидную, логично организованную и соответствующую идентичности бренда документацию. И как только вы сможете избавиться от документации — все станет радужно и прекрасно.



Под катом перевод доклада Александры Уайт, технического писателя из компании Google, на конференции Write the Docs Prague 2018. А уже через неделю 26 апреля 2019 Александра выступит на нашей конференции KnowledgeConf с докладом «How to create compelling multimedia documentation». Александра расскажет, как встроить мультимедиа форматы (видео, аудио, gif) в процесс создания артефактов и упаковки знаний, когда мультимедиа форматы подойдут лучше всего, а когда не будут работать, как измерять эффективность мультимедиа артефактов и преодолевать их ограничения.
Читать дальше →

ProКонтент 2019: конференция для технических писателей и всех, кто работает с текстами

Время на прочтение1 мин
Количество просмотров2K
Мы в каждый год устраиваем отдельную конференцию для всех, кто причастен к созданию технических текстов. В этом году она пройдет 4 апреля.

На этот раз наша конференция — особенная. И тому есть две причины. Во-первых, мы впервые пригласили внешних спикеров. От «Лаборатории Касперского» будет только два доклада, а остальные — от сотрудников компаний Intel, Positive Technologies, Logrus IT и ECommPay IT.

image
Читать дальше →

Чем занимается UX-писатель?

Время на прочтение7 мин
Количество просмотров14K
Привет, Хабр! Представляю вашему вниманию перевод статьи «What do UX writers do all day?» автора Yael Ben-David.

Осознавая тот факт, что существование такой должности, как UX-писатель, довольно спорно, непонятно, и подходит далеко не любому проекту, я все же решил рискнуть, и предложить сообществу статью, которая приоткрывает контекст работы UX-писателей. Заранее всем спасибо, кто уделит время прочтению.

image
Читать дальше →

Вредные советы: как правильно писать техническую документацию? Часть вторая

Время на прочтение10 мин
Количество просмотров6.7K
Советы по грамотному написанию технической документации для пользователей.
Часть 2


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

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

В этой части мы подробно разберем топики, из которых в основном состоит пользовательская документация (особенно User’s Guide) – а именно task-топики, в которых рассказывается, как решить конкретную задачу.

image
Читать дальше →