Комментарии 5
Интересно посмотреть как это сочетается с ГОСТами на документацию
Наверно мало сочетается. Вышеописанное больше похоже на пользовательскую документацию.
В стандартах по СИ(15288) при описании процесса:
В стандартах по ЯОД можно встретить такое описание:
Версия ИСО
про 34 гост не пишу)
А вообще, нужно уже оперировать информационными объектами, по типу моделей BIM.
Документ, нужен только для подписи и/или ознакомления, а всё остальное, должно быть в нужное время, в нужном месте. Поддерживать связи между сущностями, вот проблема.
Hidden text
Подскажите, а есть описание подхода, как правильно это межу собой переплетать?
Или "подробнее тут.." и ссылка.
Или может в споилер прятать вставки?
Или такие "заметки" выносить отдельно в виде: доп. материалы по теме.
Хороший вопрос, спасибо.
На концепции и справочники лучше всего ссылаться в тексте при первом упоминании термина. Например, в гайде "Как настроить VPN" в первой строчке у вас будет "Чтобы настроить [VPN](ссылка на концепцию, где описано что такое VPN) : ...".
А на гайды и туториалы можно ссылаться в конце раздела или параграфа. То есть в конце концепции "Что такое VPN?" у вас будет параграф типа "См. также: Как настроить VPN, Настраиваем VPN на iOS (ссылки на гайды и туториалы, соотвтетственно)".
Но это всё не правила, просто рекомендации из моего опыта. Нужно смотреть по возможности и здравому смыслу где ссылки на другие разделы будут уместны.
Для примера можете посмотреть как на пошаговые инструкции ссылаются из концепций, и наоборот, на Яндекс Облаке: https://cloud.yandex.ru/docs/managed-postgresql/concepts/backup
Diátaxis: структура технической документации