02.02.2024
techwriting
We call it "beta" because it's beta' than nothing.
У документации должна быть цель и аудитория.
- У нас молодой душный коллектив.
- Вы хотели сказать "дружный"?
- Кавычки должны быть ёлочки.
Мои странички по связанным вопросам
Ссылки могут быть нерабочими, если страница еще не опубликована.
- дни техписателей
- ссылки условно по теме
- функциональная неграмотность - про необходимость писать простые тексты и как именно это делать.
- diagrams as code
- emacs для прозы
- linters for text
- скриншотилки
- памятка по русскому языку
- OBS Studio - полезный инструмент для записи общения по видео.
- Djvu - про djvu. В работе пока не было нужно, но мало ли :)
- confluence
- docs-as-code
- BPMN
- генераторы статических сайтов
Кто такие
- https://ru.wikipedia.org/wiki/%D0%A2%D0%B5%D1%85%D0%BD%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B9_%D0%BF%D0%B8%D1%81%D0%B0%D1%82%D0%B5%D0%BB%D1%8C и https://ru.wikipedia.org/wiki/%D0%A2%D0%B5%D1%85%D0%BD%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%BE%D0%B5_%D0%BF%D0%B8%D1%81%D0%B0%D1%82%D0%B5%D0%BB%D1%8C%D1%81%D1%82%D0%B2%D0%BE (вторая статья беднее и сильно пересекается с первой).
- https://classinform.ru/profstandarty/06.019-tekhnicheskii-pisatel-spetcialist-po-tekhnicheskoi-dokumentatcii-v-oblasti-informatcionnykh-tekhnologii.html — профстандарт.
В нём мне, как ИП, интересно отнесение к видам экономической деятельности:- 62.0 - Разработка компьютерного программного обеспечения, консультационные услуги в данной области и другие сопутствующие услуги
- 63.11 - Деятельность по обработке данных, предоставление услуг по размещению информации и связанная с этим деятельность
- https://digitalbroccoli.com/2021/07/06/techwriter-how-to/ - кто такие в ракурсе «хочу этим работать»
Нужность обществу
- https://habr.com/ru/post/659191/
- https://habr.com/ru/company/orioninc/blog/565098/ - техрайтеры и Agile.
- https://habr.com/ru/post/549588/ - о доках для нужд команды.
- https://habr.com/ru/company/moysklad/blog/535230/ - а нафига и с какого момента начинать.
https://habr.com/ru/post/665782/ - «Импортозамещение по советской модели. Выводы из ошибок будут сделаны?» - про сложности с обнаружением и передачей технологий. Про то, что происходит, если сохранение и передача знаний не налажены, в том числе даже обнаружение, что сохранять-то, но и что можно иначе ж.
Что такое полноценная технологическая компетенция?
- Умение делать некий технологический процесс, т.е. наличие обученных данной технологии работников;
- Знание как делать этот технологический процесс, т.е. максимально подробное описание действий работников;
- Знание почему этапы этого технологического процесса надо делать именно так, а не иначе.
Причём, перечисленные пункты находятся в неразрывной связи. Т.е. ущерб для одного из них неминуемо повлечёт деградацию двух других.
П.1 страдал от отсутствия полноценных п.2 и п.3, поскольку передача умений от поколения к поколению без 2-го и 3-го пункта приводила к их постепенной деградации.
Печалится о том, что исключения единичны и системой не поддерживаются. Такой вот выход на общественное, куда я эту ссылку тож добавила.
Некоторые места общения
- https://t.me/twriters техрайтеры и госты.
- https://t.me/technicalwriters - и ещё техрайтеры.
- https://t.me/techwriters
- https://t.me/docsascode
- https://www.reddit.com/r/technicalwriting/
- https://t.me/technical_writing (канал)
- https://t.me/shut_up_and_write (канал)
Обучение
- https://roadmap.sh/technical-writer — версия, что надо. Спорная, конечно.
- https://developers.google.com/tech-writing/overview - гуглокурсы, 2шт
- https://stepik.org/course/684/promo#toc - английский + техрайтерство
- https://starkovden.github.io/index.html - вольный перевод курса Documenting APIs: a guide for technical writers (https://idratherbewriting.com/learnapidoc/), составленного Томом Джонсоном, техническим писателем Amazon). Переводчик - @starkovden (tg, github). …разберете API на составные части, узнаете о конечных точках, параметрах, типах данных, аутентификации, curl, JSON, командной строке, консоли разработчика Chrome, JavaScript и прочих деталях, связанных с REST API.
Модули курса:- Введение в REST API (https://starkovden.github.io/about-first-module.html)
- Используем API как разработчики (https://starkovden.github.io/about-second-module.html)
- Документирование конечных точек (https://starkovden.github.io/about-third-module.html)
- Спецификация OpenAPI и Swagger (https://starkovden.github.io/about-fourth-module.html)
- Тестирование документации (https://starkovden.github.io/about-fifth-module.html)
- Концептуальные разделы (https://starkovden.github.io/about-sixth-module.html)
- Публикация документации (https://starkovden.github.io/about-seventh-module.html)
- Работа технического писателя (https://starkovden.github.io/about-eigth-module.html)
- Нативные библиотеки API (https://starkovden.github.io/about-ninth-module.html)
- Глоссарий API и источники (https://starkovden.github.io/about-tenth-module.html)
- Документирование кода (https://starkovden.github.io/about-eleventh-module.html)
- Английский:
- https://habr.com/ru/company/plesk/blog/650779/ - про английский. Больше UX/UI, но не только.
- https://study.com/academy/course/technical-writing-course.html - англоязычный курс
- https://developers.google.com/tech-writing/overview
Все посты