Technical Writing 101 🇺🇦

Доступны записи API THE DOCS, AMSTERDAM:

- Lorna Jane Mitchell: GitHub as a Landing Page
- Aaron Verber: Leaping Forward: Finding the Future of Your API Docs
- Sven Strack: Engineer Stunning (API) Documentation
- Jaap Brasser: Advancing Your API Strategy in an Infrastucture World
- Anthony Roux: What Makes an API Product Successful
- Maria Garcia: Bulletproofing Your APIs: Why Users' Feedback Matters
- Mark Simpson, Alexandra Stramarko: Business Integration Made Easy with APIs
- Kelsey Lambert, Sejal Parikh: An Inside Look at a Large-scale Writer-driven REST API Doc Solution at Salesforce
- Alvaro Navarro: Effective API Governance: Lessons Learnt
- Phil Sturgeon: API Descriptions as Production Code
- Steph Shin: How to Embed UX Thinking in your Next API

https://pronovix.com/event/api-docs-amsterdam-2019

#conference #video #en

Переведенный курс Тома Джонсона по документированию API обзавёлся сайтом:

https://starkovden.github.io/

#API #resource #ru

Самое раннее из известных технических руководств на английском языке, о том, как работать с астрономическими инструментами, было написано Джеффри Чосером в 1391 году.

https://en.wikipedia.org/wiki/A_Treatise_on_the_Astrolabe

#vintage #en

https://habr.com/ru/post/414757/

#DocsAsCode #ru #article

Как быстро создавать новые документы в Гугл-доках

Вводите в адресной строке:

— Документ: doc.new
— Таблица: sheet.new
— Презентация: slide.new
— Форма: form.new

Несколько дельных советов UX писателям о том, как повысить свою визибилити (простите я устал) и получить больше признания а работу, которую вы делаете!

Words matter. Writers matter. You matter.

https://medium.com/dropbox-design/getting-a-seat-at-the-table-as-a-ux-writer-da63303d5b1d

#uiux #en #article #resource

Немного про UI/UX

https://dou.ua/lenta/articles/ux-guide/

#uiux #ru

https://twitter.com/zachlieberman/status/1179789258724446208

#example #en

Частенько слышу про замкнутый круг "не берут на работу без опыта, где взять опыт, если не берут на работу без него" и вот вам молниеносное решение проблемы — Hacktoberfest.

Вот вам отфильтрованный по нужным параметрам и лейблам поиск по Гитхабу, контрибьють — не хочу! Есть таски на все уровни скилла и познаний, дерзайте!

On a side note: наша библиотека ngx-bootstrap тоже участвует в Hacktoberfest

#vacancy #career #en

Technical Writing 101 🇺🇦 pinned «Привет! Если вы читали описание канала, то могли заметить, что я работаю техрайтером в компании Valor Software (на самом деле нас тут уже двое.) Так вот, случилось так, что мы ищем новых людей (техрайтеров, офк). Если вы живете в Украине, но будет еще круче…»

Привет!

Если вы читали описание канала, то могли заметить, что я работаю техрайтером в компании 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

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

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

#tool #en

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

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

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

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

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

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

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

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

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

Вот хорошая цитата из гайдлайна 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.»

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

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

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

https://www.publisheet.com/

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

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

#tool

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

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

#article #en #SSG

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

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

Из нового:

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

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

#tool #testthedocs #en