Архив с CAD-файлом и фотографиями ещё не является документацией роботизированной платформы. Пользователю нужно понять назначение конструкции, определить её версию, собрать совместимый комплект, не перепутать соединения, запустить программное обеспечение, выполнить безопасную проверку и найти причину сбоя.
Документация должна провести его через весь этот маршрут. Поэтому полезнее считать не количество файлов, а вопросы, на которые они действительно отвечают.
Редакционная карта комплекта. Она показывает роли документов, а не готовность материалов конкретной версии «Зари 40».
Короткий ответ: десять обязательных слоёв
| Слой | Главный вопрос пользователя | Типичные артефакты |
|---|---|---|
| 1. Назначение и границы | Что это и чего от конструкции не следует ожидать? | обзор, область применения, ограничения |
| 2. Версия и статус | К какой конфигурации относятся сведения? | ID версии, дата, статус, совместимость |
| 3. Быстрый старт | Как осмотреть и подготовить систему к первому безопасному действию? | quick start, stop-условия, ссылки на подробные процедуры |
| 4. Состав и BOM | Какие именно детали образуют эту версию? | BOM, обозначения, производители, допустимые замены |
| 5. Механика и CAD | Как устроены детали, крепления и интерфейсы? | исходные CAD, экспортные форматы, чертежи, допуски |
| 6. Электрика | Как соединены питание, защита, привод и сигналы? | принципиальная и монтажная схемы, распиновки, журнал проводов |
| 7. ПО и конфигурация | Как получить воспроизводимое поведение? | исходный код, зависимости, параметры, сборка, прошивка |
| 8. Испытания | Что действительно проверено и в каких условиях? | методики, протоколы, исходные данные, результаты и отказы |
| 9. Безопасность и обслуживание | Какие опасности, проверки и интервалы известны? | risk register, предупреждения, осмотр, замена, утилизация |
| 10. Изменения и поддержка | Что изменилось и где искать решение проблемы? | changelog, известные дефекты, диагностика, контакты поддержки |
Эти слои не обязаны быть десятью отдельными PDF. Для малого проекта несколько ролей можно объединить. Важно, чтобы сведения имели понятный адрес, версию и владельца.
1. Назначение раньше технических деталей
Первый документ отвечает не на вопрос «из чего сделано?», а на вопрос «для чего существует эта конфигурация?». Здесь нужны:
- краткое назначение;
- предполагаемые пользователи;
- среда и режим применения;
- подтверждённые возможности;
- известные ограничения;
- статус: концепт, прототип, испытано или доступно.
OSHWA рекомендует начинать открытый аппаратный проект с понятного описания его идентичности и назначения. Это защищает пользователя от необходимости угадывать смысл конструкции по деталям или репозиторию.
2. Версия связывает все остальные документы
Фраза «актуальная схема» бессмысленна, если неизвестно, для какой сборки она актуальна. Версия должна связывать BOM, CAD, электрику, прошивку, параметры и протоколы испытаний.
В NASA Systems Engineering Handbook configuration management включает идентификацию конфигурации, управление изменениями, учёт статуса и проверку. Для DIY-проекта масштаб проще, но причинная логика та же: без уникального обозначения нельзя доказать, что тест и схема относятся к одному физическому объекту.
Минимальная карточка версии содержит ID, дату, перечень ключевых узлов, ссылки на документы и список отличий от предыдущей версии.
3. Quick start не должен притворяться полной инструкцией
Короткий стартовый документ нужен, чтобы пользователь:
- определил версию;
- проверил комплектность и видимые повреждения;
- нашёл обязательные предупреждения;
- понял, какие действия пока запрещены;
- перешёл к подходящей подробной процедуре.
Quick start не должен помещать сложную сборку или опасную настройку в пять красивых шагов. Его задача — безопасно направить, а не сократить инженерную реальность.
4. BOM: не перечень покупок, а состав версии
Хороший bill of materials связывает позицию с обозначением на схеме или в CAD. Обычно полезны:
- reference ID;
- производитель и точный part number;
- количество;
- функция;
- источник или поставщик;
- цена и дата цены, если она фиксируется;
- допустимая замена и основание совместимости;
- статус: установлен, заказан, снят с производства или неизвестен.
OSHWA отдельно подчёркивает, что состав не следует вынуждать восстанавливать по проектным файлам: нужен самостоятельный BOM, а обозначения должны сопоставляться с чертежами и схемами.
5. CAD нужен и в исходном, и в доступном формате
Для изменения конструкции нужен исходный параметрический файл. Для просмотра, изготовления и проверки часто нужны экспортные форматы: STEP, STL, DXF, PDF или другие, подходящие конкретному процессу.
Один STL полезен для печати, но обычно плохо объясняет замысел и историю параметров. Один нативный файл может оказаться недоступен человеку без нужной программы. OSHWA рекомендует публиковать исходники вместе с форматами обмена и экспорта.
Возле файла должны находиться единицы измерения, версия, материал, критические размеры и связь с физически проверенной деталью.
6. Электрическая документация состоит из нескольких представлений
Принципиальная схема объясняет электрические связи и функции. Монтажная схема показывает физическое подключение. Распиновка описывает конкретный разъём. Журнал маркировки помогает найти провод в реальной сборке.
Ни одно представление не заменяет остальные. Фотография аккуратной коробки не сообщает допустимый ток, а таблица проводов не показывает защиту цепи.
Для каждой схемы нужны версия, питание, обозначения узлов, состояние по умолчанию, предупреждения и ссылка на совместимую конфигурацию. Практический шаблон уже подготовлен в разделе «Маркировка проводов».
7. ПО — это код плюс способ воспроизведения
Исходники без версии зависимостей и параметров могут собраться иначе или не собраться вообще. Документация программного слоя включает:
- поддерживаемую версию аппаратуры;
- среду сборки;
- зависимости и их версии;
- конфигурационные файлы;
- команду сборки и запуска;
- способ загрузки прошивки;
- параметры, единицы и безопасные значения по умолчанию;
- тесты и ожидаемый результат;
- лицензию.
ROS 2 Developer Guide связывает качество пакета с версионированием, документацией и тестами, а в структуре репозитория отдельно выделяет README, документацию, конфигурацию, тесты, лицензию и changelog.
8. Испытание без условий не превращается в характеристику
Заявление «проехала», «держит нагрузку» или «не перегрелась» невозможно повторить без условий. Протокол должен фиксировать:
- вопрос испытания;
- версию объекта;
- метод и измерительные средства;
- поверхность, температуру и другие значимые условия;
- последовательность;
- stop-условия;
- исходные данные;
- результат и наблюдаемые отказы;
- отклонения от методики;
- дату и проверяющего.
Программа испытаний говорит, что планируется проверить. Протокол сообщает, что произошло в одном конкретном тесте. Сводная характеристика появляется только после достаточного числа сопоставимых результатов.
9. Безопасность проходит через весь комплект
Предупреждения нельзя складывать в один файл и считать задачу закрытой. Опасность должна быть видна там, где человек принимает решение: в quick start, схеме питания, инструкции, настройке ПО, методике теста и обслуживании.
Документируют известные опасности, защитные барьеры, допустимые роли, подготовку зоны, аварийную остановку, действия после отказа и критерии запрета запуска. Отсутствие проведённой оценки обозначается прямо.
10. Changelog превращает папку в историю решений
Название final_final_точно_final не является системой версий. Журнал изменений должен объяснять:
- какая версия выпущена;
- когда;
- что изменилось;
- какие документы и узлы затронуты;
- есть ли несовместимость;
- какие ошибки известны;
- как вернуться к предыдущему состоянию.
GitHub Releases связывает выпуск с конкретной точкой истории через tag и позволяет приложить release notes и готовые файлы. Даже если проект не использует GitHub, полезен сам принцип: набор для повторения должен быть заморожен и отличим от текущей рабочей папки.
Проверка полноты: не «файл есть», а «вопрос закрыт»
Для каждого слоя поставьте один из четырёх статусов:
- нет — документ отсутствует;
- черновик — структура или сведения есть, но не проверены;
- проверено — документ сверили с указанной версией;
- повторено — другой человек смог выполнить описанное действие или получить сопоставимый результат.
CSV намеренно не содержит оценки в процентах. Десять зелёных строк не компенсируют отсутствие критической схемы питания или stop-условий. Важнее видеть конкретный пробел и следующий артефакт.
Как выглядит минимальный выпуск версии
Для раннего прототипа разумный минимальный пакет может состоять из:
- карточки назначения, статуса и ограничений;
- ID конфигурации и даты;
- BOM установленной версии;
- механической и электрической схемы в достаточном для понимания виде;
- исходников ПО и инструкции воспроизведения;
- предупреждений и stop-условий;
- хотя бы одного проверенного протокола;
- changelog;
- списка известных неизвестных.
Это ещё не обязательно инструкция к самостоятельной сборке. Публикация фактов о прототипе и публикация проверенного руководства — разные уровни ответственности.
Текущий статус «Зари 40»
В проекте уже существуют отдельные факты, дневник, карта документации, программа испытаний, образовательные статьи и несколько самостоятельных шаблонов. Но этот материал не объявляет полный комплект конкретной платформы готовым.
Для каждой физической версии ещё предстоит связать точный состав, схемы, ПО, ограничения и результаты. Поэтому общая карта документации служит архитектурой будущей базы знаний, а не витриной несуществующих файлов.
«Заря 40» — открытый дневник разработки и испытаний нескольких вариантов роботизированных платформ, доступных для изучения, доработки и адаптации под разные задачи.
Основные источники
- OSHWA, Best Practices for Open Source Hardware.
- NASA, Systems Engineering Handbook, Revision 2, раздел 6.5.
- ROS 2, Developer Guide.
- GitHub Docs, About releases.
Сквозной пример: документ не живёт в одиночестве
Для учебного прототипа T‑01 одна строка должна пройти цепочку версия → BOM → схема → конфигурация ПО → протокол → результат. Например, запись «датчик D‑01» содержит part number и ревизию в BOM; его разъём есть на схеме; конфигурация знает его ID; тест отвечает на один вопрос; в журнале остаётся результат с условиями. Пустой CSV без такого заполненного маршрута — только список полей. OPEN!NEXT показывает, что документация для повторного использования охватывает не только сборку, но и использование и обслуживание.