learning-course

Полезные материалы по курсу технического документирования:

• Technical Writer. Roadmap for anyone looking for a career in technical writing https://roadmap.sh/technical-writer (русскоязычная версия)

• Профстандарт 197 https://fgosvo.ru/uploadfiles/profstandart/06.019.pdf

• Книга «Техническая документация информационных систем» http://lib.ulstu.ru/venec/disk/2017/460.pdf

• Разработка технической документации, Вадим Глаголев: https://djvu.online/file/oJAAVWz7GUO8T

• Корректура https://moodle.kstu.ru/pluginfile.php/273789/mod_resource/content/1/Корректура.%20Учебник.pdf

• Уайт, Ян В. Редактируем дизайном. — М. Издательский дом «Университетская книга», 2009. — X, 244 с. https://drive.google.com/open?id=1MO2A_MO9rFjAByZQzBafRvUawIuzs-w3

• Карл Вигерс. Разработка требований к программному обеспечению: https://biconsult.ru/img/bi_portal/Razrabotka_trebovanii_Karl_Vigers.pdf

• SRS по Вигерсу https://analytics.infozone.pro/requirements-analysis/template-specification-requirements/

• Требования для программного обеспечения: рекомендации по сбору и документированию https://vk.com/doc63393685_444611874?hash=D7INqptGUz9UGJYqx3kr5ORpjJYImfL2OC3TREC06Nw

• Требования. Системная инженерия, лекция 4 https://studfile.net/preview/2152457/

ГОСТы:

• Справочник по техническим документам — Гостопедия. Инициатор проекта – Философт

• ГОСТ серии 19 и 34 http://www.rugost.com/index.php?option=com_content&view=category&id=19&Itemid=50

• ГОСТ Р ИСО/МЭК 15910-2002. Процесс создания документации пользователя программного средства http://gostrf.com/normadata/1/4294817/4294817037.pdf

• РД 50-34.698-90 Методические указания. Информационная технология. Комплекс стандартов и руководящих документов на автоматизированные системы. Требования к содержанию документов https://c-kd.ru/d/rd-50-34.698-90.pdf. Заменен на ГОСТ Р 59795–2021 «Комплекс стандартов на автоматизированные системы. Автоматизированные системы. Требования к содержанию документов» https://www.swrit.ru/doc/gost34/59795-2021.pdf

• Описание организации информационной базы http://www.rugost.com/index.php?option=com_content&view=article&id=172&catid=26&Itemid=63

• ГОСТ Р 58609— 2019/ISO/IЕС/IЕЕЕ 15289:2017. Требования к составу и содержанию различных информационных элементов (документации), которые должны предусматриваться к разработке или пересмотру жизненного цикла системы, программных средств и процессов обслуживания: https://files.stroyinf.ru/Data2/1/4293726/4293726316.pdf

• ГОСТ 7.32-2017. Система стандартов по информации, библиотечному и издательскому делу. Отчет о научно-исследовательской работе https://www.rea.ru/ru/org/managements/orgnirupr/Documents/gost_7.32-2017.pdf

• ГОСТ Р 7.0.97-2016. Система стандартов по информации, библиотечному и издательскому делу https://eos.ru/upload/pril_norm_akt/GOST_P_%207.0.97-2016.pdf

• ГОСТ 8.417-2002. Государственная система обеспечения единства измерений https://astro.insma.urfu.ru/sites/default/files/upload_files/doc/gost_8.417-2002.pdf

Руководства по стилю:

• Руководство по стилю русского языка в рамках локализации https://www.microsoft.com/ru-ru/language/styleguides (использовать его нужно аккуратно и разумно, не все примеры в нем хороши и не все рекомендации стоит брать на вооружение)
• Методическое и справочное руководство по переводу на русский язык, тематическому редактированию, литературной правке и редакционно-издательскому оформлению инженерно-технической документации https://storage.piter.com/upload/new_folder/978538800101/metodichka_2007_04_bp.pdf
• Стиль изложения документации пользователя программного средства https://philosoft-services.com/standard/gostr_project_styleguide_071207.pdf
• Кагарлицкий, Юрий Валентинович. Разработка документации пользователя программного продукта: (методика и стиль изложения) / Ю. В. Кагарлицкий. - Москва : Философт Сервисы, 2012 скачать конспект
• Шаблон Стайлгайда, автор – Полина Никонова
• Проект Глоссария

Редстандарты (можно вдохновляться):

• Тинькофф-журнал. Руководство для авторов. Максим Ильяхов, Саша Рай, 2014—2019 гг. https://docs.google.com/document/d/14XdGIjVJLM_FsjHzyh5ca8PkffngykzXd2bLPHzA2ME/edit#
• Модульбанк. Написано в июле 2016, автор — Людмила Сарычева. https://docs.google.com/document/d/1c_2uP1PpiM12h1ee8egVXAoUCJ9mE9r68zMqrqmS8VA/edit
• Mailchimp Content Style Guide https://styleguide.mailchimp.com/

Англоязычная литература:

• The Microsoft Manual of Style; git-версия The Microsoft Manual of Style
• Docs for Developers: An Engineer’s Field Guide to Technical Writing (2021). Автор: Jared Bhatti, https://vk.com/doc255577237_616040006?hash=3q9IYa52IoFRnHHtn7hCObEnp9E7HKsK8xhltV5OAUP
• Technical Writing 101: A Real-World Guide to Planning and Writing Technical Documentation. Автор: Alan S. Pringle, скачать книгу
• Список книг по работе с требованиями https://www.processimpact.com/pubs.html
• DocBook XSL: The Complete Guide. Bob Stayton, http://www.sagehill.net/docbookxsl/index.html

Видеоматериал:

• Профессиональный стандарт «Технический писатель». Михаил Острогорский (DocFactor'16) https://www.youtube.com/watch?v=KBiEkOLFnNw (правовая природа; как выглядит профстандарт; основные области компетентности и уровни квалификации; различия в профессиях техписа и аналитика)
• Через тернии к звездам – от неструктурированного контента к CMS, Елена Федотова https://dzen.ru/video/watch/6246d8c77cb10b6bb2dedfb0?f=d2d
• Контент-стратегия, Елена Федотова: https://yandex.ru/video/preview/9288001768253760432
• О технической документации Documentat.io https://www.youtube.com/live/w0DNTDE3EgE?si=r0h89VT_RV6o0M4l
• Documentat.io ГОСТ 34 (1 часть https://www.youtube.com/watch?v=Cb7oyeIjWZ8, 2 часть https://www.youtube.com/watch?v=NLXbsE_HOJY, 3 часть https://www.youtube.com/watch?v=O9896hB0DSM)
• Documentat.io ГОСТ 19 https://www.youtube.com/watch?v=1P18VkS7ORQ
• Конференции ПроТекст: https://protext.su/pro/events/ («Видеодокументация», «Инструменты технического писателя», вебинар для руководителей «Техническое документирование для бизнеса: проблемы и решения»)
• Kaspersky Tech. База знаний здорового техписа: https://careers.kaspersky.ru/events/kaspersky-tech-knowledge
• ProКонтент 2019: три хардовых доклада и частушка: https://habr.com/ru/companies/kaspersky/articles/448430/
• Виды требований к ПО и способы их документирования (функциональные и нефункциональные требования, бизнес требования и требования стейкхолдеров; инструменты – user story, use cases) https://www.youtube.com/watch?v=GVmDXR_Qg2c (Надежда Тарасова, DataArt)
• Виды и примеры требований https://www.youtube.com/watch?v=CUmKvqGgWMc (Денис Бесков, 2013)
• Оценка трудозатрат и сроков документирования https://www.youtube.com/watch?v=qpcfAPnsBTE (Александр Лебедев, "Философт")
• Локализация документации (documentat.io) https://www.youtube.com/watch?v=UYRKX1ZuUzw
• Требования к документационному инструментарию (documentat.io) https://www.youtube.com/watch?v=Sawz84gY4Uk (Основы – для чего нужен инструментарий (разработка, ревью, хранение, публикация). Но, конечно, не про создание процессов ревью)
• Cloud.ru конференция технических писателей – Редполитика: как написать правила и не устроить бои без правил; Линтер для технической документации: кейс с Vale; Система метрик клиентской документации; Частые ошибки техписателей в поиске работы

Справочники, словари, рекомендации по работе с текстом:

• Ильяхов maximilyahov.ru
• Розенталь www.rosental-book.ru и другие словари и справочники
• http://gramota.ru/ поиск по орфографическому, толковому и другим словарям. При поиске слов можно использовать подстановочные символы звездочка (*) и вопросительный знак (?). Пример: бэк*
• Орфографический академический ресурс «АКАДЕМОС»: поддерживаемый ИРЯ РАН агрегатор актуальных орфографических норм
• Лев Успенский «Слово о словах»
• Нора Галь «Слово живое и мёртвое» https://dramafond.ru/wp-content/uploads/2014/12/Nora_Gal_Slovo_zhivoe_i_mertvoe.pdf
• Мильчин. Справочник издателя и автора https://vk.com/doc205672900_491943677?hash=7rZ6yUooOFXoRJH56dPcwKQiwkITzlzCnLlesacVpzH и editorium.ru
• Правила орфографии и пунктуации https://therules.ru/
• Как писать рук-во пользователя – https://tdocs.su/1391
• Рекомендации по оформлению текстов от РИА
• Словарь сокращений https://www.sokr.ru/с./

Интересные статьи:

• Требования ГОСТ на автоматизированные системы в ИБ-проектах. Что изменилось и как это применять? https://habr.com/ru/company/angarasecurity/blog/671882/
• Документирование по ГОСТ 34* — это просто (плюсы и минусы) https://habr.com/ru/post/122700/
• Как писать техническое задание на программу по ГОСТ 19.201-78? https://tdocs.su/12215
• Стандарты и шаблоны для ТЗ на разработку ПО https://habr.com/ru/post/328822/
• Правила составления Software requirements specification (читать вместе с комментариями) https://habr.com/ru/post/52681/
• ГОСТ-овский стиль управления. Статья Gaperton по правильной работе с ТЗ по ГОСТ https://gaperton.livejournal.com/49867.html
• Принцип единого источника. Часть II (профилирование, компоновка, параметризация) https://ru-techwriters.livejournal.com/15793.html
• Культура локализации ПО, есть ли она? https://habr.com/ru/post/573834/
• 10 отличий локализации от перевода https://translator-school.com/blog/lokalizaciya-igr-i-perevod-v-chem-raznicza
• Разработка документации при помощи DocBook: https://habr.com/ru/post/212881/
• Ланит: О нашем умении писать по-русски IT-документацию https://habr.com/ru/companies/lanit/articles/722224/
• Внешний вид и скриншоты в пользовательской документации. Как надо и не надо делать (Анастасия Дмитриева): https://habr.com/ru/companies/aktiv-company/articles/524838/

Инструменты:

• Типограф https://www.artlebedev.ru/typograf/ для улучшения экранной типографики
• Утилита «Новый взгляд» http://www.kirsanov.com/fresheye/ для исключения речевых ошибок
• Яндекс Спеллер помогает находить и исправлять орфографические ошибки https://yandex.ru/dev/speller/
• Онлайн-сервисы для оценки читаемости текста: http://readability.io/ и https://glvrd.ru/ (для английского языка – https://hemingwayapp.com/)
• Умная проверка пунктуации, грамматики и стилистики на основе машинного обучения: https://orfogrammka.ru/
• Модель ruGPT-3 XL содержит 1,3 млрд параметров и умеет продолжать тексты на русском и немного на английском языках https://russiannlp.github.io/rugpt-demo/
• Инструменты для перевода: https://www.deepl.com/translator и https://www.translate.ru/перевод
• Инструмент для моделирования диаграмм и блок-схем бизнес-процессов https://app.diagrams.net/

Docs as code

• Docs as code на примере Foliant https://www.youtube.com/watch?v=6CKVodl2YcA (полезное видео про легковесные языки разметки – markdown, reStructuredText, AsciiDoc; про системы контроля версий)
• Markdown Cheat sheet https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
• reStructuredText Cheat Sheet https://docutils.sourceforge.io/rst.html#user-documentation

Курсы:

• Курс по написанию спецификации API https://starkovden.github.io/openapi-tutorial-overview.html

UML:

• Онлайн редакторы PlantText UML: https://www.planttext.com/ и https://plantuml-editor.kkeisuke.com
• Справочное руководство по языку PlantUML (Version 1.2021.2) https://pdf.plantuml.net/PlantUML_Language_Reference_Guide_ru.pdf оригинал
• Справочное руководство по UML с быстрым стартом https://plantuml.com/ru/deployment-diagram
• Справочное руководство "Неочевидный PlantUML" https://telegra.ph/non-obvious-plantuml-1-09-23
• Самоучитель UML, Леоненков А.В.
• Язык UML. Руководство пользователя, Гради Буч
• UML. Основы, 3-е издание. Фаулер Мартин
• UML: обзор основных типов диаграмм (цикл статей): Часть 1 диаграмма классов, Часть 2 диаграмма компонентов, Часть 3 диаграмма объектов, Обзор 14 диаграмм UML

Регулярные выражения (regexp):

• Основы https://habr.com/ru/articles/545150/
• Инструмент самопроверки https://regex101.com/