Technical Writing 101 🇺🇦

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

Вот парочка сервисов/приложений которые вспомнились:

1. https://asciinema.org/ — Самая продвинутая из подобных утилит. Позволяет cохранять и в пару кликов шарить весь записанный процесс. Можно даже встраивать плеер с записью на странички. Сайт очень красивый и можно поглазеть на чужие ASCII анимации.

2. https://github.com/icholy/ttygif — делает скрин каждого кадра и склеивает это все в gif.

3. https://github.com/nbedos/termtosvg — Утилита написана на Python, сохраняет все в SVG анимацию

4. https://github.com/chjj/ttystudio — просто и со вкусом, на выходе выплевывает gif или APNG. Никаких зависимостей.

5. https://showterm.io/ — записывает весь процесс работы выбранной консольной утилиты и позволяет легко шарить результат, можно даже не устанавливать, а скормить в терминал bash <(curl record.showterm.io)

#screenshot #tool #en

Краткий (очень) разбор преимуществ reStructuredText vs Markdown для написания технической документации

https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/

#reStructuredText #markdown #article #en

Приятный сайт для создания “скриншотов” кода. Много тем, большой выбор подсветки синтаксиса, умеет PNG и SVG

https://carbon.now.sh

#screenshot #tool #en

Благое дело люди делают! Все еще надеюсь что однажды что-то пригодное для продакшена типа такого будет, чтоб и с графиками и поддержкой всяких markdeep и чтоб все само.

Markdown база знаний: https://habr.com/post/415865/

#knowledgemanagement #en

Очень, ну очень разумная мысль — изучать технологию параллельно создавая туториал по ней. И сам изначально больше поймешь, а когда нужно будет снова к ней вернуться можно глянуть что ты сам же и написал: https://nanxiao.me/en/learn-new-technology-through-writing-a-tutorial-about-it/

#article #en

Подоспели видеоматериалы с Мини-Гипербатона про текстовые редакторы, но при беглом осмотре — слабовато, у меня про retext и remark намного полезнее:
https://events.yandex.ru/events/hyperbaton/24-may-2018/

#ide #video #conference

https://tldrlegal.com/ — отличный по реализации, но удручающий по смыслу сервис. На сайте собраны всемозможные software лицензии (GPL, MIT и т.д) описанные максимально простым языком, который понимают все, а не только юристы. This is how documentation should work

#legal #en

Какая удобная штука!

https://www.screely.com/

TO INSTALL DOOM II:
1. Go to A or B Drive
2. Type INSTALL and press ENTER

#vintage #en

Можно даже понаблюдать как в 1995-ом выглядели багтрекинговые утилиты

Я люблю смотреть на профессию технического писателя более широко, поэтому вот вам отличный кусок видео-документации от Sega, 1996го года. По сути это "trainumentary" которое описывает базовые принципы профессии и более специфичные детали о работе тестером в самой Sega https://vimeo.com/166472288

#vintage #en #video

При поиске новой работы писателем, у вас наверняка попросят примеры прошлых работ и чтобы позорно не отправлять гору док-файлов предлагаю вам обратить внимание на сервис который поможет легко, и, что немаловажно, красиво организовать свою работу в аккуратное портфолио https://www.clippings.me/

Пример готового портфолио: http://www.mila-carter.com/

#career #en

Хороший пример подачи документации в IKEA-стиле, в виде картинок/комиксов https://code-cartoons.com/

#example #en

Абсолютно никак не могу понять, зачем создают вот такие https://danmoop.github.io/plume/ проекты. И тысячи их на всяких producthunt, 3.5 базовых фичи для написания текста, одна более-мене уникальная и все. Просто окошко для набора текста. Остановитесь, пожалуйста.

#ide #en

Markdown в Telegram

#markdown #en