Tools

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

Для документации

- Paligo. В эту программу постарались вместить все, что нужно техническому писателю: единый источник, фильтрация контента, публикация в разных форматах, версионирование, ветки. Интегрируется с кучей всего, например, можно публиковать в Zendesk Guide, GitHub или BitBucket. Есть менеджмент переводов, мне особенно понравился менеджмент скриншотов для разных языков.
🤑Бесплатная пробная версия на 30 дней, а еще подробный хелп и видеоуроки.

- Elevio. Это не просто CMS (content managment system), a целый набор инструментов для интеграции справки в интерфейс. Например, с помощью инструмента Helpers можно сделать контекстную справку (к каждой странице интерфейса можно добавить какую-то статью хелпа) и всплывающие подсказки (к какому-то элементу интерфейса можно добавить поясняющий текст). Обычно для создания всех этих штук нужно привлекать разработчиков, а тут можно без. Еще есть интеграция с разными чатами, например, Intercom. В хелпе пишут про поддержку многоязычного контента и даже что-то про автопереводы, но я не пробовала.
🤑Бесплатная пробная версия на 14 дней. Для регистрации мне понадобилась почта на домене .biz.

Для текстов интерфейса

- Strings. Решает проблему, когда вы увидели опечатку в интерфейсе и нужно опять просить разработчика что-то поправить. Подключаете Strings к Github, писатель редактирует тексты в Strings, оттуда они попадают в Github, а там уже разработчики сами как-то с этим пулреквестом разбираются.
🤷‍♀️Выглядит удобно, но я не попробовала, потому что у них закрытое бета-тестирование.

- Frontitude. Frontitude интегрируется с Figma (программа, где работают дизайнеры). Тексты автоматически попадают из Figma в Frontitude. Затем писатель работает с текстом только во Frontitude: редактирует, согласовывает и обсуждает. При этом текст всегда можно посмотреть в текущем дизайне без перехода в Figma. Суперфишка этого приложения — это контроль голоса и тона. В прошлом посте писала, что такое есть только у Grammarly, но вот еще один пример. Обещают сделать интеграцию с другими дизайнерскими программами: Adobe Xd и Sketch.
💸Есть бесплатная версия.

- Writeon. Позволяет отредактировать текст на любом сайте. Это почти как поправить текст через Инструменты разработчика, только не нужно открывать код страницы. А еще вы сможете поделиться ссылкой на сайт с новым текстом.
🤑Бесплатная пробная версия на 14 дней.

Для переводов

- Phrase. Я не специалист в локализации, поэтому просто посмотрела. Мне понравилась возможность переводить контент прямо на сайте, сразу понятно, влезет текст или нет. Вот демо, можете сами попробовать. И куда же теперь без плагинов Figma и Sketch. С помощью плагинов можно выгрузить текст с макетов дизайнеров, перевести его и загрузить обратно.
💸Есть бесплатная версия.

#тулзы

Tools 2

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

Для документации

- Allwrite docs. Для тех, кто хочет сделать свою документацию из файлов Google Docs. Никакого языка разметки знать не надо, Allwrite docs сам конвертирует ваши файлы в html и markdown.
💸Бесплатно.

- PerfectIt. Плагин для Word. Находит опечатки и ошибки, проверяет пунктуацию в списках и таблицах, заглавные буквы и дефисы. Можно добавить свои правила.
🤑Бесплатная пробная версия на 14 дней.

- Readme. Генератор для API документации. Редактирование в markdown, импорт из Swagger или OpenAPI Spec, управление версиями, есть готовые темы. В платной версии есть встроенная аналитика для API.
💸Есть бесплатная версия.

- Write good. Линтер, который может найти пассивный залог и слова, которые не несут смысловой нагрузки в документации, например, just, really, very, extremely. Только en.
💸Бесплатно.

- IBM Style guide. Линтер, который проверяет документ на соответствие IBM writing style guide. Только en.
💸Бесплатно.

Для переводов

- Weblate. Поддерживает много форматов перевода, к переводу можно добавить контекст (скриншот или описание), можно настроить проверки качества перевода.
💸Есть бесплатная версия.


Мне про него рассказал @crrlcx, вот его отзыв:
Близок по возможностям к Phrase, Strings, Localise и Crowdin, к тому же может использоваться не просто как внешний сервис, но и как собственный.
На Weblate остановились из-за 2 вещей — его можно запустить у себя и он базируется на фреймворке django, в котором у наших разработчиков есть достаточно компетенций, чтобы вносить исправления или создавать плагины и не ждать вендора.
Плюсом, который не был очевиден сначала, оказалась открытость Weblate, так что наши внутренние исправления можно было предложить проекту сразу на github в виде пуллреквеста.

#тулзы

Swimm

Swimm — программа для создания документации. Позволяет встроить написание документации в процесс разработки. Такой подход называется Continuous Documentation. Например, можно вставить в документацию кусок кода, когда этот код изменится в исходнике, он изменится в документации. Кроме кусков кода можно вставить в документацию имена файлов или переменных, они тоже будут обновляться вместе с исходным кодом. Если какой-то документ стал не актуальным после изменений кода, то программа отметит его.

Есть плагины для VSCode и IntelliJ. При использовании плагина в коде будут видны ссылки на документацию. Документация открывается в IDE, то есть рядом с кодом, без переходов на другие сайты.

Интерфейс и некоторый фичи похожи на Confluence, например то, как код добавляется в документацию.

Сейчас Swimm в бета тестировании. Видео о том, как начать работать.

#тулзы

API Explorers or Try it

Продолжу про API Explorer. Вот у каких компаний мне удалось его найти:

- Facebook API Explorer. Доступен только после регистрации. Без регистрации можно посмотреть инструкцию к нему.

- Asana API Explorer. И них у тоже есть инструкция к нему.

- Google API Explorer и инструкция.

- Adyen API Explorer. Они планируют выложить его в открытый доступ, но пока еще нет.

- DocuSign API Explorer и API Request Builder. Писала про них выше.

Как можно сделать самим

Вам понадобится Open API спецификация, потому что все инструменты, которые я знаю, за основу берут ее.

Потом можно взять готовое и платное решение:
- APIMATIC
- Redocly
- Apiary

Или воспользоваться чем-то бесплатными и доработать:
- Swagger UI или он же, но в более современном дизайне
- RapiDoc
- Readme
- Rhosys
- DapperDox
- Adyen API Explorer, но тут нужно подождать, пока его выложат в open source

#developerexperience #тулзы