Size: a a a

Technical Writing 101

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

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

https://www.publisheet.com/

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

UPD2: Не лежит, просто нужно (пока что) обязательно заходить на www.-версию сайта
источник
2019 September 22
Technical Writing 101
Редакция канала в полном составе отправляется в отпуск. По возможности буду что-то постить, но ничего не обещаю. До скорых встреч и хорошей всем рабочей недели :3
источник
Technical Writing 101
источник
2019 September 25
Technical Writing 101
Мы потом напишем

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

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

Вот хорошая цитата из гайдлайна 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.»
источник
Technical Writing 101
Маша дело говорит. Фраза номер 1 в моем рейтинге — «Надо вчера». Это как раз последствие «Мы потом напишем». Вот цитата из гайда Microsoft на русском:

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

Понятный текст — очень важная часть работающего интерфейса. Лучше встроить работу с профессиональным писателям и редакторами в дизайн-процессы. Сделайте так, чтобы они на ранних этапах приступали к работе, ведь проблемы с формулировками часто вскрывают проблемы с дизайном. Если у вашей команды есть проблемы с объяснением дизайна, часто улучшения нужны дизайну, а не объяснениям.»
источник
2019 September 27
Technical Writing 101
Налоговая служба Украины написала документацию к своему электронному кабинету на Sphinx/reST. В сайте узнаётся тема Read the Docs, можно скачать PDF и EPUB. Я считаю, для госоргана это очень круто и современно.

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

Не хватает только кода на гитхабе и простого канала обратной связи. Нашёл баг, ищу как зарепортить. :)
источник
2019 October 08
Technical Writing 101
И мы снова на связи!

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

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

со мной можно связаться прямо через ТГ, пишите.
источник
2019 October 11
Technical Writing 101
Частенько слышу про замкнутый круг "не берут на работу без опыта, где взять опыт, если не берут на работу без него" и вот вам молниеносное решение проблемы — Hacktoberfest.

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

On a side note: наша библиотека ngx-bootstrap тоже участвует в Hacktoberfest
источник
Technical Writing 101
источник
Technical Writing 101
Немного про UI/UX

https://dou.ua/lenta/articles/ux-guide/
источник
2019 October 12
Technical Writing 101
Несколько дельных советов UX писателям о том, как повысить свою визибилити (простите я устал) и получить больше признания а работу, которую вы делаете!

Words matter. Writers matter. You matter.

https://medium.com/dropbox-design/getting-a-seat-at-the-table-as-a-ux-writer-da63303d5b1d
источник
2019 October 14
Technical Writing 101
Как быстро создавать новые документы в Гугл-доках

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

— Документ: doc.new
— Таблица: sheet.new
— Презентация: slide.new
— Форма: form.new
источник
Technical Writing 101
technical_writing
Все мы любим Docs as a Code, но иногда этого становится мало и хочется ВСЁ as a Code, поэтому в сегодняшней подборке Презентации as a Code (с уклоном в Markdown)

Начну со своих любимых тулз:

Marp — нЕкогда Electron (не переставайте читать на этом месте) приложенька, которая кушает маркдаун и делает из них собсно презентацию, но товарищи разработчики видимо протёрли глаза и наконец поняли что Электрон — есть корень зла и свернули сие богомерзкое деяние в пользу богоподобного расширения для VS Code

Deckset — если в вашем распоряжении есть MacOS и необходимость хоть изредка делать презентации то просто жмите на ссылку и дальше не читайте. Лучшая аппка.

reveal.js — фреймворк для HTML-презентаций. Умеет вложенные солайды, Markdown ☜(゚ヮ゚☜), экспорт в PDF, отдельные спикер ноуты. Если впадлу что-то там мудрить, то есть онлайн-редактор. Можно закомбинить это дело с Pandoc.

remark.js — чуть более tricky, чем reveal, но дело делает. Есть подсветка кода в слайдах, нормально всё скейлится, конечно же умеет MD, отдельные спикер ноуты и всякое такое.

hackMD — это как Google Docs, но для Markdown. Тут оно за тем, что там есть режим презентаций :}

Не про Markdown, но Slides as a Code вполне себе — eagle.js — фреймворк для слайдов поверх Vue.js. Самая выпендрёжная из всех систем в списке, без лишних слов:  посмотрите демки, до конца.

Notable mentions:

md2googleslides — если вы всё никак не слезете с иглы гугло-экосистемы, то вот можете писать в md, но конвертить во всё тот же Google Slides.

It Is Wednesday, My Dudes, хорошего дня :}
источник
2019 October 15
Technical Writing 101
Обратите внимание на LiquiDoc Ops

https://www.agyl.dev/
источник
Technical Writing 101
источник
Technical Writing 101
источник
Technical Writing 101
источник
Technical Writing 101
источник
2019 October 16
Technical Writing 101
Самое раннее из известных технических руководств на английском языке, о том, как работать с астрономическими инструментами, было написано Джеффри Чосером в 1391 году.

https://en.wikipedia.org/wiki/A_Treatise_on_the_Astrolabe
источник