Не совсем техрайтинг, но буквы и цифры все еще присутствуют и я думаю в наших (техрайтерских) силах влиять на такое — пропорциональный vs моноширинный шрифты в динамических элементах интерфейса.

https://blog.usejournal.com/proportional-vs-monospaced-numbers-when-to-use-which-one-in-order-to-avoid-wiggling-labels-e31b1c83e4d0

Просто посмотрите на приведенные примеры-картинки в статье. Меня, лично, очень бэдит с такого, давайте вместе стараться, чтобы вот так небыло.

#uiux #visual #en #resource

Technical Writing: Readability and Text Metrics

Из этой книги вы узнаете:

- Почему метрики важны в техническом письме.
- Как измерить эффективность вашей документации.
- Топ 5 текстовых метрик для пользовательской документации.
- Как проверять техническую документацию на ошибки.
- Где взять все необходимые метрики.

#metrics #en

Читая местные техрайт чаты и наблюдая повторяющиеся изо дня в день вопросы, всё меньше боюсь постить сюда что-то очевидное (но, конечно, полезное), поэтому ловите 9 действительно хороших, годных советов по UX-райтингу (не обращайте внимание на название статьи, внутри релевантно):

https://medium.com/@johnamwill/9-simple-but-powerful-ux-writing-tips-for-designers-83ec1ca96561

#uiux #article #en

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

Если вы пишете документацию, заполните опрос. Так вы поможете JB сделать хороший и полезный инструмент. Опрос короткий, у меня он занял вдумчивых 15 минут.

Дастин Морис Горски, мейнтейнер фреймворка Giraffe, делится своими наблюдениями и мыслями по поводу документации опенсорс проект(а)ов:

https://dusted.codes/open-source-documentation

key takeaway из статьи:

I put all initial documentation into the README.md file inside my Git repository.

Almost two years-, nearly 50 releases-, 47 total contributors-, more than 800 GitHub stars and more than 100 merged pull requests later the project's simple documentation approach hasn't changed much, and to be honest I have very little motivation to do something about it.

The main reason why I'm not particularly excited about migrating Giraffe's documentation to a different place is because I actually believe that the current way of how documentation is handled by Giraffe is a perfectly well working solution for its users, its contributors and myself.

In Giraffe the entire documentation - a full reference of what the web framework can or cannot do and how it integrates and operates within the ASP.NET Core pipeline - is placed in a single DOCUMENTATION.md file inside the project's Git repository, right next to the README.md file.

#en #article #resource

Трансляция Write the Docs Prague.

Сегодня и завтра в Праге проходит конференция Write the Docs.

Программа на сегодня, 16 сентября:

— The Super Effective Writing Process of Grammy-winning Artists

— How to write the perfect error message

— How to launch your startup with good docs

— Surprise! You're a designer now

— Documenting known unknowns

— Write the API docs before the API exists

— Disagree with “I Agree”. Enforcing better data privacy through the language of documentation

— Inclusive environments are just better: science says so

Есть бесплатная трансляция: https://www.writethedocs.org/conf/prague/2019/livestream/.

Еще только вторник, а отличные новости уже подоспели.

Новый мажорный релиз всеми любимого инструмента тестирования документации Vale! Теперь 2.0!

Из нового:

[brkng] Vale теперь не содержит в себе сторонних проверок. write-good, proselint, Joblint и другие теперь вынесены в отдельный репозиторий;
[new] Можно линтить XML, в т.ч DITA;
[new] Расширенные скоупы проверок, позволяющие более гранулировано писать правила для линтера;
[new] Добавлен опциональный параметр --config, позволяющий вручную указать путь к файлу конфигурации.

Очень и очень круто!

#tool #testthedocs #en

Люблю читать всевозможные документация-рилейтед саксесс-стори. В этот раз про успешный перекат на #AsciiDoc

https://medium.marqeta.com/write-your-developer-docs-in-asciidoc-78febf2a1304

#article #en #SSG

Нравятся всяикие около "юниксвэйные" тулзы и сервисы, которые делают что-то одно, но хорошо (ну, +- хорошо). Не знаю, как и кому это может быть полезно, но малоли!

Publisheet — сервис, позволяющий ээ.. захостить функционирующую эксельку в вебе в красивой обёрточке

https://www.publisheet.com/

UPD: Сервис лежит, 🤷‍♀️

UPD2: Не лежит, просто нужно (пока что) обязательно заходить на www.-версию сайта

#tool

Мы потом напишем

«Мы потом напишем хелп/подсказки/текст в интерфейсе», — следующая по популярности фраза в моем персональном рейтинге.

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

Вот хорошая цитата из гайдлайна Microsoft:
«Software developers often think of text as relegated to product documentation and technical support. "First we'll write the code, and then we'll hire someone to help us explain what we have developed." Yet in reality, important text is written earlier in the process, as the UI is conceived and coded. This text is, after all, seen more frequently and by more people than perhaps any other type of technical writing.
Comprehensible text is crucial to effective UI. Professional writers and editors should work with software developers on UI text as an integral part of the design process. Have them work on text early because text problems often reveal design problems. If your team has trouble explaining a design, quite often it is the design, not the explanation, that needs improving.»

Маша дело говорит. Фраза номер 1 в моем рейтинге — «Надо вчера». Это как раз последствие «Мы потом напишем». Вот цитата из гайда Microsoft на русском:

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

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

Налоговая служба Украины написала документацию к своему электронному кабинету на Sphinx/reST. В сайте узнаётся тема Read the Docs, можно скачать PDF и EPUB. Я считаю, для госоргана это очень круто и современно.

https://cabinet.tax.gov.ua/help/intro.html

Не хватает только кода на гитхабе и простого канала обратной связи. Нашёл баг, ищу как зарепортить. :)

И мы снова на связи!

Salesforce заопенсорсили свой проект — Metro. Он создавался техническим писателем компании как внутренняя тулза. Это скрипт\приложение на Python, который преобразовывает Google Docs или Salesforce Quip в страницы которые понимает Confluence. Проект находится в активной разработке, доки можно глянуть в readthedocs репе. (зачем было разносить это всё по разным местам — решительно неясно)

#tool #en

Привет!

Если вы читали описание канала, то могли заметить, что я работаю техрайтером в компании Valor Software (на самом деле нас тут уже двое.) Так вот, случилось так, что мы ищем новых людей (техрайтеров, офк). Если вы живете в Украине, но будет еще круче, если вы живете в Харькове, и ищете работу — гоу к нам!

У нас приятно, бродит три кота, офис около реки и все оч даже адекватные. Стек компании — JS, TS, Node, Angular, а скоро, возможно, будет и React. Стек техрайтерский — зависит от проекта, но скорее всего по классике, может быть Конфлюенс, может быть статический сайт с Markdown, может быть Zendesk. Если не устраивает что-то по технологиям, вдруг вы ненавидите Zendesk и фанатеете от Asciidoc, — мы открыты к предложениям, обсудим. У нас довольно плоская управленческая структура, есть CEO и есть вся Команда, никаких "эффективных менеджеров" и прочей лабуды, но печеньки таки вкусные и они есть :} А, а еще у нас есть опция релокейта!

Больше деталей в полной вакансии на DOU. Я знаю, что техрайтерам часто ненравятся чужие буквы, но опять же, мы (я) открыты к критике, если что-то в вакансии выглядит уж совсем отвратительно, оригинал вакансии доступен для комментирования.

Контакты:

Cвязаться с HR напрямую:
anna.siver@valor-software.com
elena.malko@valor-software.com

Основное контактное мыло:
contact@valor-software.com

со мной можно связаться прямо через ТГ, пишите.

#vacancy #career