Материалы для разработки технической документации

Основы профессии технического писателя

• 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
• 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://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/
• Список книг по работе с требованиями https://www.processimpact.com/pubs.html

UML

• Что такое UML? http://book.uml3.ru/sec_1_1
• Статьи про разные виды диаграмм с заданиями https://github.com/kolei/PiRIS/blob/master/articles/5_1_1_10_uml_use_case.md
• Справочное руководство по языку 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-е издание. Фаулер Мартин
• Обзор основных типов диаграмм (цикл статей): Часть 1 диаграмма классов https://habr.com/ru/articles/738428/, Часть 2 диаграмма компонентов https://habr.com/ru/articles/756552/, Часть 3 диаграмма объектов https://habr.com/ru/articles/800849/
• Обзор 14 диаграмм UML https://habr.com/ru/articles/508710/

Корректура и редактура

• О редактировании и редакторах. Составитель — Аркадий Эммануилович Мильчин https://editorium.ru/
• Корректура https://moodle.kstu.ru/pluginfile.php/273789/mod_resource/content/1/Корректура.%20Учебник.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/
• Озон: стайлгайд, в котором собраны правила написания и оформления статей https://docs.ozon.ru/styleguide/?__rr=1&abt_att=1&origin_referer=habr.com
• The Microsoft Manual of Style https://sbaratz.com/shc/MicrosoftManualOfStyleForTechnicalPublications-V3.pdf
• git-версия The Microsoft Manual of Style https://github.com/MicrosoftDocs/microsoft-style-guide/blob/main/styleguide/welcome/index.md

Глоссарий

• Глоссарий ИТ-терминов (СберТех) https://gitverse.ru/sbertech/it-glossary/content/master/glossary.md
• Cloud Native Glossary https://github.com/cncf/glossary/tree/91af09ab3e4e4e2888b3ef45a53f560b6599ca2f
• Словарь терминов Госуслуг

Справочники, словари

• Ильяхов maximilyahov.ru
• Розенталь и другие словари и справочники https://rosental-book.ru/
• http://gramota.ru/ поиск по орфографическому, толковому и другим словарям. При поиске слов можно использовать подстановочные символы звездочка () и вопросительный знак (?). Пример: бэк
• Орфографический академический ресурс «АКАДЕМОС»: поддерживаемый ИРЯ РАН агрегатор актуальных орфографических норм https://orfo.ruslang.ru/search/word
• Мильчин. Справочник издателя и автора https://vk.com/doc205672900_491943677?hash=7rZ6yUooOFXoRJH56dPcwKQiwkITzlzCnLlesacVpzH
• Словарь сокращений https://www.sokr.ru/с./
• Словарь терминов по фронтенду https://github.com/web-standards-ru/dictionary/blob/main/dictionary.md#deprecated
• Рекомендации по оформлению текстов от РИА https://design-education.ru/new/ria-rules.pdf
• Правила орфографии и пунктуации https://therules.ru/

Методические материалы

• Как делать редполитику: поясняю на примере Ozon https://dump-ekb.ru/kak-delat-redpolitiku-poyasnyayu-na-primere-ozon?ysclid=mmnbfmasfa604280223
• Как писать рук-во пользователя – https://tdocs.su/1391

ГОСТ

• Сравочник по техническим документам — Гостопедия https://gost34.ru/index.php?title=Справочник_по_техническим_документам. Инициатор проекта – Философт
• ГОСТ серии 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.pd

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

UX-писатель

• Уайт, Ян В. Редактируем дизайном. — М. Издательский дом «Университетская книга», 2009. — X, 244 с. https://drive.google.com/open?id=1MO2A_MO9rFjAByZQzBafRvUawIuzs-w3
• Озон: гайд по текстам в интерфейсе https://www.figma.com/proto/4u5dhL9svYYysmn6xPiTu4/Гайд-по-текстам-в%C2%A0интерфейсе?node-id=67-65212&amp%3Bstarting-point-node-id=67%3A65212

Инструменты

• Типограф 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/
• Онлайн редакторы PlantText UML: https://www.planttext.com/ и https://plantuml-editor.kkeisuke.com
• Regexp Инструмент самопроверки https://regex101.com/

Книги про текст и язык

• Лев Успенский: «Слово о словах»
• Корней Чуковский: «Живой как жизнь»
• Нора Галь: «Слово живое и мёртвое» https://dramafond.ru/wp-content/uploads/2014/12/Nora_Gal_Slovo_zhivoe_i_mertvoe.pdf

Курсы

• Курс по написанию спецификации API https://starkovden.github.io/openapi-tutorial-overview.html
• Обзорный курс «Техническая документация в IT-проектах» от Documentat.io https://rutube.ru/plst/900993/

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

• Требования ГОСТ на автоматизированные системы в ИБ-проектах. Что изменилось и как это применять? 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://habr.com/ru/articles/661695/
• Continuous Documentation, MVD и документация как продукт: три подхода, которые изменят ваше представление о документации https://habr.com/ru/articles/901254/

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

• Профессиональный стандарт «Технический писатель». Михаил Острогорский (DocFactor'16) https://vk.com/video-130432849_456239022 (правовая природа; как выглядит профстандарт; основные области компетентности и уровни квалификации; различия в профессиях техписа и аналитика)
• Через тернии к звездам – от неструктурированного контента к CMS, Елена Федотова https://dzen.ru/video/watch/6246d8c77cb10b6bb2dedfb0?f=d2d
• Контент-стратегия, Елена Федотова: https://dzen.ru/video/watch/6246d9feca338466e22df8ec
• Текст как интерфейс, Елена Федотова: https://rutube.ru/video/a53be7d5a1d7fe948e26055539671c80/
• Конференции ПроТекст: 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://rutube.ru/video/5a1b7c98bc3d6d25a3b3eed513e5215f/ (Надежда Тарасова, DataArt)
• Виды и примеры требований https://rutube.ru/video/76ed908259c26740b994e278c821a1e6/ (Денис Бесков, 2013)
• Оценка трудозатрат и сроков документирования https://rutube.ru/video/ef430336f4e3301688c7a7de5675927f/ (Александр Лебедев, "Философт")
• Глоссарий Госуслуг. Зачем мы написали словарь, если уже есть Даль и Ожегов? https://vimeo.com/1071322738
• Cloud.ru Редполитика: как написать правила и не устроить бои без правил: https://vkvideo.ru/playlist/-182881521_6/video-182881521_456239395?linked=1
• Cloud.ru Линтер для технической документации: кейс с Vale https://vkvideo.ru/playlist/-182881521_6/video-182881521_456239394?linked=1
• Cloud.ru Система метрик клиентской документации https://vkvideo.ru/playlist/-182881521_6/video-182881521_456239393?linked=1
• Cloud.ru Частые ошибки техписателей в поиске работы https://vkvideo.ru/playlist/-182881521_6/video-182881521_456239392?linked=1
• Единый источник в документации — подходит вашей команде или нет? https://rutube.ru/video/fbd53dfd70bf7018e620ab64b02d789e/