Здравствуйте!
Можно добавить информацию о стилистике документации: какие слова использовать, как строить предложения, оформлять списки и таблицы, что такое стайлгайды. Для вдохновения посмотрите курс от Гугла: https://developers.google.com/tech-writing/overview

А еще можно накидать темы: стандарты в документации, рецензирование и оценка качества, docs as code, иллюстрирование:  скриншоты, диаграммы, инструменты

Напишите в чат https://t.me/technicalwriters, возможно, там будет больше ответов

Спасибо за советы)

🤝

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

у докера можно сразу щупать трогать поднимать контейнеры вроде

Часто проблема в данных возникает, особенно если мы говорим про какие-то системы построения отчётов.
Большую БД вы, конечно, можете засунуть в докер, но нужно ли оно?

Может быть легче поднимать тестовый стенд?

зачем большую? Речь идет о «потыкать чтобы пощупать»

Сложно пощупать систему построения отчётов без достаточного количества данных.

Да, упаковав все в докер можно добиться того, чтобы проект разворачивался одним кликом на любой ОС. Но много нюансов.

Легче развернуть тестовый стенд на серваке и отсылать пользователя туда.

Задался тут одним интересным вопросом: есть ли кто из участников применявший NLG(Natural language generation) для документации?

Привет всем новоприбывшим! Откуда вы?

Всем привет! У меня вопрос по Notion - мы решили им пользоваться для нашей внутренней базы знаний в компании, но не понимаем, как правильны выстроить схему доработки и апдейтов документов.

Например, у нас есть процедура "оформление нового сотрудника" и соответствующий документ, в котором она описана. Это версия 1.0

Дальше мы где-то в отдельном месте собираем комментарии и правки, и когда из накапливается некое  количество, перерабатываем документ, чтобы получилась версия 1.2 (мы хотим делать так, а не вносить сразу каждое маленькое исправление, чтобы не долбать менеджеров постоянными апдейтами)

Так вот, как это организовать технически? Мы копируем страницу "Документ 1.0", вносим правки в копию, называем ее " Документ 1.2" и выкатываем? Тогда у нас сломается линковка.
Или мы делаем копию и ее кладем в архив (которого у нас нет, но можно сделать), а правки вносим прямо в рабочий документ?
А как при этом не потерять историю правок и изменений?

Я практически уверена, что есть готовые решения, но не понимаю даже какие ключевые слова вбить в гугл, чтобы их найти(

Нюанс: я менеджерка в анимационной студии, и подавляющее большинство наших сотрудников вообще не знакомы ни с идеей итеративного обновления документации, ни тем более со специфическими инструментами типа гит.

В notion нет встроенной истории версий? И вам прям очень важна история в формате какая строка поменялась или можно обойтись описанием изменения в одном предложении? Тогда можете наверху документа держать секцию changelog дата, что поменялось, номер версии и почему

Посмотрела: для платных командных пространств есть page history у notion

Спасибо! Я на самом деле не до конца понимаю, что нам нужно, а что нет, но на всякий случай хочется не терять прошлые версии

Поэтому хочется посмотреть как другие компании работают с такими штуками

Пока что единственный релевантный нам пример который я знаю - это система PEP у комьюнити Python, но нам нужно что-то значительно более простое

Звучит так, будто вам бы хватило Confluence. А причем здесь PEP питона я вообще не понял)

Да Гитбук с таким на раз справляется.

Confluence дорогой для нас
Pep притом что у них очень продуманная система того как вносятся, апрувятся и логируются изменения