Навеяно статьёй " 4 стихии программной документации: The Grand Unified Theory of Documentation"
Попробуем применить эту теорию к рабочим продуктам ШСМ.
Авторы “теории” выделяют документы четырёх типов:
- Tutorials — учебник.
- How-to guides — руководство.
- Reference — справочник.
- Explanation — объяснение.
Учебник — это документ, который помогает превратить ученика-читателя в пользователя системы. Документы-учебники обычно самые объёмные в пакете документации. При этом писать их непросто, ведь они должны быть простыми для понимания, содержательными и при этом тщательно выверенными и надёжными.
Все курсы ШСМ являются учебниками.
Руководство знакомит читателя с шагами, необходимыми для решения реальной рабочей задачи. Оно отличается от учебника тем, что ориентировано на читателей с базовым опытом работы с системой. Руководство даёт ответ на вопрос, который может сформулировать только пользователь с некоторым опытом.
Не могу пока назвать никакие материалы ШСМ “руководствами”.
У справочников есть только одна функция — описательная. В конечном счёте в справочнике всё сводится к описанию кода системы, параметров интерфейса или формата файлов. Справочник может содержать примеры, иллюстрирующие использование системы, но не должен содержать объяснение основных понятий или описание способов решения задач пользователей. Справочник содержит техническую информацию, но не содержит инструкции. Во многих случаях справочники удобно генерировать автоматически — на основе исходного кода системы. Справочник вряд ли можно назвать интересным чтением, его цель — сделать поиск и получение технической информации максимально быстрым и эффективным.
Не могу пока назвать никакие материалы ШСМ “справочниками”.
Проект справочника http://sewiki.ru по СМ создал и ведёт Юрий Ежков @yur15t
Объяснение предназначено для подробного углублённого описания конкретной темы. Этот тип документа позволяет расширить описание системы, рассмотреть систему с более высокого уровня или даже с разных точек зрения. В документации на некоторые системы объяснение не выделяется в отдельный документ, а разбросано по другим документам в виде примечаний или дополнительных вставок. Объяснение гораздо сложнее создавать, чем документы других типов. Оно требует аналитического подхода.
“Объяснения” в неструктурированном (пока?) виде накапливаются здесь, на платформе systemsworld.club.