Скриншоты! Как много в этом слове!
Излюбленная тема всех техрайт чатиков — обсуждать в какой тулзе они делают скрины, но это так же скучно, как слушать про чужие сны. Давайте лучше почитаем свежую статью из ISTC Communicator о том, как сделать так, чтобы снятием свежих скринов нужно было заниматься не каждый апдейт продукта. А поможет нам это сделать simplified user interface, относительно свежий подход к созданию таких себе "абстрактных" версий скриншотов интерфейса (см рис.1).
Если вам интересно почитать еще об этом, то там в конце статьи есть раздел Further Reading, а если хочется вдобавок и пообщаться про это, то для этих дел есть отдельный (англоязычный) Слак-чат
#screenshot #tool
Излюбленная тема всех техрайт чатиков — обсуждать в какой тулзе они делают скрины, но это так же скучно, как слушать про чужие сны. Давайте лучше почитаем свежую статью из ISTC Communicator о том, как сделать так, чтобы снятием свежих скринов нужно было заниматься не каждый апдейт продукта. А поможет нам это сделать simplified user interface, относительно свежий подход к созданию таких себе "абстрактных" версий скриншотов интерфейса (см рис.1).
Если вам интересно почитать еще об этом, то там в конце статьи есть раздел Further Reading, а если хочется вдобавок и пообщаться про это, то для этих дел есть отдельный (англоязычный) Слак-чат
#screenshot #tool
Forwarded from DocOps
Introducing Markdown and Pandoc.
В этом месяце вышла новая книга про документацию как код: «Introducing Markdown and Pandoc: Using Markup Language and Document Converter», автор Thomas Mailund.
Если что, Markdown — это самый популярный (хотя не самый мощный) формат разметки, а Pandoc — универсальный конвертер между десятками форматов документов.
Книга начинает с основ Markdown и доходит до использования шаблонов и фильтров (препроцессоров) в Pandoc. Меня особенно порадовала глава про фильтры с примерами кода на Python и panflute. Когда-то я пытался писать фильтры для Pandoc, но не осилил, пришлось обрабатывать уже готовый HTML. Теперь сделаю ещё одну попытку.
Книгу можно купить на сайте издательства. Приятного чтения!
В этом месяце вышла новая книга про документацию как код: «Introducing Markdown and Pandoc: Using Markup Language and Document Converter», автор Thomas Mailund.
Если что, Markdown — это самый популярный (хотя не самый мощный) формат разметки, а Pandoc — универсальный конвертер между десятками форматов документов.
Книга начинает с основ Markdown и доходит до использования шаблонов и фильтров (препроцессоров) в Pandoc. Меня особенно порадовала глава про фильтры с примерами кода на Python и panflute. Когда-то я пытался писать фильтры для Pandoc, но не осилил, пришлось обрабатывать уже готовый HTML. Теперь сделаю ещё одну попытку.
Книгу можно купить на сайте издательства. Приятного чтения!
Все мы любим 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, хорошего дня :}
#tool #markdown #ide
Начну со своих любимых тулз:
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, хорошего дня :}
#tool #markdown #ide
yhatt.github.io
Marp - The simplest markdown presentation writer
It's a time to migrate into Marp Next!
Не совсем техрайтинг, но буквы и цифры все еще присутствуют и я думаю в наших (техрайтерских) силах влиять на такое — пропорциональный 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
https://blog.usejournal.com/proportional-vs-monospaced-numbers-when-to-use-which-one-in-order-to-avoid-wiggling-labels-e31b1c83e4d0
Просто посмотрите на приведенные примеры-картинки в статье. Меня, лично, очень бэдит с такого, давайте вместе стараться, чтобы вот так небыло.
#uiux #visual #en #resource
Medium
Proportional vs. Monospaced Numbers: When to use which one in order to avoid “Wiggling Labels”
Technical Writing: Readability and Text Metrics
Из этой книги вы узнаете:
- Почему метрики важны в техническом письме.
- Как измерить эффективность вашей документации.
- Топ 5 текстовых метрик для пользовательской документации.
- Как проверять техническую документацию на ошибки.
- Где взять все необходимые метрики.
#metrics #en
Из этой книги вы узнаете:
- Почему метрики важны в техническом письме.
- Как измерить эффективность вашей документации.
- Топ 5 текстовых метрик для пользовательской документации.
- Как проверять техническую документацию на ошибки.
- Где взять все необходимые метрики.
#metrics #en
Читая местные техрайт чаты и наблюдая повторяющиеся изо дня в день вопросы, всё меньше боюсь постить сюда что-то очевидное (но, конечно, полезное), поэтому ловите 9 действительно хороших, годных советов по UX-райтингу (не обращайте внимание на название статьи, внутри релевантно):
https://medium.com/@johnamwill/9-simple-but-powerful-ux-writing-tips-for-designers-83ec1ca96561
#uiux #article #en
https://medium.com/@johnamwill/9-simple-but-powerful-ux-writing-tips-for-designers-83ec1ca96561
#uiux #article #en
Medium
9 simple but powerful UX writing tips for designers
In Design in Tech 2017, John Maeda’s seminal annual report, Maeda notes that “code is not the only unicorn skill.” His nomination for the…
Forwarded from DocOps
JetBrains давно используют собственный инструмент для документации, а теперь хотят его опубликовать.
Если вы пишете документацию, заполните опрос. Так вы поможете JB сделать хороший и полезный инструмент. Опрос короткий, у меня он занял вдумчивых 15 минут.
Если вы пишете документацию, заполните опрос. Так вы поможете 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
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
dusted.codes
Open Source Documentation
Programming Adventures
Forwarded from DocOps
Трансляция 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/.
Сегодня и завтра в Праге проходит конференция 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/.
Интересный подход к процессу ревью\апдейта документации внедряет Британский Government Digital Service.
(GDS — Британская контора, которая (как я понял) топит за цифровизацию всевозможных гос. процессов)
GDS написали своего бота\тулзу, который(ая) напоминает проверить актуальность доки. Каждая страница имеет 3 переменные: дату последней проверки, кто должен ее просмотреть, и как скоро страница должна быть снова пересмотрена.
Больше инфы на офсайте и в гитхаб репе. Ничего сверхсложного, простая и действительно рабочая задумка + забавный маскот-собачка.
#tool #en
(GDS — Британская контора, которая (как я понял) топит за цифровизацию всевозможных гос. процессов)
GDS написали своего бота\тулзу, который(ая) напоминает проверить актуальность доки. Каждая страница имеет 3 переменные: дату последней проверки, кто должен ее просмотреть, и как скоро страница должна быть снова пересмотрена.
Больше инфы на офсайте и в гитхаб репе. Ничего сверхсложного, простая и действительно рабочая задумка + забавный маскот-собачка.
#tool #en
Еще только вторник, а отличные новости уже подоспели.
Новый мажорный релиз всеми любимого инструмента тестирования документации Vale! Теперь 2.0!
Из нового:
[brkng] Vale теперь не содержит в себе сторонних проверок. write-good, proselint, Joblint и другие теперь вынесены в отдельный репозиторий;
[new] Можно линтить XML, в т.ч DITA;
[new] Расширенные скоупы проверок, позволяющие более гранулировано писать правила для линтера;
[new] Добавлен опциональный параметр --config, позволяющий вручную указать путь к файлу конфигурации.
Очень и очень круто!
#tool #testthedocs #en
Новый мажорный релиз всеми любимого инструмента тестирования документации Vale! Теперь 2.0!
Из нового:
[brkng] Vale теперь не содержит в себе сторонних проверок. write-good, proselint, Joblint и другие теперь вынесены в отдельный репозиторий;
[new] Можно линтить XML, в т.ч DITA;
[new] Расширенные скоупы проверок, позволяющие более гранулировано писать правила для линтера;
[new] Добавлен опциональный параметр --config, позволяющий вручную указать путь к файлу конфигурации.
Очень и очень круто!
#tool #testthedocs #en
GitHub
Release v2.0.0-beta · errata-ai/vale
This is the first pre-release on the path to Vale 2.0, which includes a number of new features and a few implementation changes.
Breaking Changes
Vale no longer includes write-good, proselint, or ...
Breaking Changes
Vale no longer includes write-good, proselint, or ...
Люблю читать всевозможные документация-рилейтед саксесс-стори. В этот раз про успешный перекат на #AsciiDoc
https://medium.marqeta.com/write-your-developer-docs-in-asciidoc-78febf2a1304
#article #en #SSG
https://medium.marqeta.com/write-your-developer-docs-in-asciidoc-78febf2a1304
#article #en #SSG
Medium
Write your developer docs in AsciiDoc
Don’t play the CMS game — read how Marqeta leveraged free tools like Gatsby and AsciiDoc to build a modern docs site.
Нравятся всяикие около "юниксвэйные" тулзы и сервисы, которые делают что-то одно, но хорошо (ну, +- хорошо). Не знаю, как и кому это может быть полезно, но малоли!
Publisheet — сервис, позволяющий ээ.. захостить функционирующую эксельку в вебе в красивой обёрточке
https://www.publisheet.com/
UPD: Сервис лежит, 🤷♀️
UPD2: Не лежит, просто нужно (пока что) обязательно заходить на www.-версию сайта
#tool
Publisheet — сервис, позволяющий ээ.. захостить функционирующую эксельку в вебе в красивой обёрточке
https://www.publisheet.com/
UPD: Сервис лежит, 🤷♀️
UPD2: Не лежит, просто нужно (пока что) обязательно заходить на www.-версию сайта
#tool
Редакция канала в полном составе отправляется в отпуск. По возможности буду что-то постить, но ничего не обещаю. До скорых встреч и хорошей всем рабочей недели :3
Forwarded from Shut up and write
Мы потом напишем
«Мы потом напишем хелп/подсказки/текст в интерфейсе», — следующая по популярности фраза в моем персональном рейтинге.
Хелп, подсказки и текст в интерфейсе — это часть продукта, с которой пользователи будут взаимодействовать. Скорее они заметят ошибку в тексте, чем баг в бэкенде, тем более большинству все равно на безупречную архитектуру.
Если писать тексты потом, после дизайна и разработки, то мы можем получить сложную программу с непонятными названиями в интерфейсе. Да, хелп к такой системе будут много читать, но кому от этого легче?
Вот хорошая цитата из гайдлайна 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.»
«Мы потом напишем хелп/подсказки/текст в интерфейсе», — следующая по популярности фраза в моем персональном рейтинге.
Хелп, подсказки и текст в интерфейсе — это часть продукта, с которой пользователи будут взаимодействовать. Скорее они заметят ошибку в тексте, чем баг в бэкенде, тем более большинству все равно на безупречную архитектуру.
Если писать тексты потом, после дизайна и разработки, то мы можем получить сложную программу с непонятными названиями в интерфейсе. Да, хелп к такой системе будут много читать, но кому от этого легче?
Вот хорошая цитата из гайдлайна 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.»