Соглашение по структуре каталогов и файлов документации в репозитарии

Иерархия каталогов верхнего уровня и вложеных поддиректорий

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

raspildocs
 |
 |-/developer_conventions (ветка "Стандарты проектирования и програмирования")
 |  |-/_drafts
 |  |-/document_standart (подветка "Стандарты документации")
 |
 |-/development_environment (ветка "Среда и инструменты разработки")
 |  |-/_drafts
 |  |-/components (ветка "Компоненты")
 |  |-/ide (ветка "IDE")
 |  |-/test (ветка "Unit Test")
 |  |-/vcs (ветка "VCS")
 |  |-/firebird (ветка Firebird)
 |  
 |-/others (ветка "Остальные")
 |-/projects (ветка "Описания проектов и библиотек")
 |-/roadmap (ветка "План развития (Roadmap)")

Не следует изменять без крайней необходимость иерархию каталогов первого и второго уровня.

Иерархия файлов в каталогах верхнего уровня

raspildocs
 |
 |-/developer_conventions
 |  |-/_drafts
 |  |  |-dummy.file
 |  |-/document_standart
 |  |  |-main.md
 |  |-main.md
 |
 |-/development_environment
 |  |-/_drafts
 |  |  |-dummy.file
 |  |-/components
 |  |  |-main.md
 |  |-/ide
 |  |  |-main.md
 |  |-/test
 |  |  |-main.md
 |  |-/vcs
 |  |  |-main.md
 |  |-/firebird
 |  |  |-main.md
 |  |-main.md
 |  
 |-/others
 |  |-/_drafts
 |  |  |-dummy.file
 |  |-main.md
 |  
 |-/projects
 |  |-/_drafts
 |  |  |-dummy.file
 |  |-main.md
 |  
 |-roadmap
 |  |-/_drafts
 |  |  |-dummy.file
 |  |-main.md
 |
 |-book.json
 |-README.md
 |-SUMMRY.md

Папка _drafts используется для черновиков. Формат черновиков .txt или .md.
Файл dummy.file используется как заглушка для синхронизации с Git пустой папки _drafts. Не следует создавать папкe _drafts в других дирректориях.

Документ main.md является страницей указателем на подразделы нижнего уровня или именем документа выделенного в отдельную дирректорию.

Если создаваемый или редактируемый документ будет содержать внутренние ссылки на файлы или картинки, то его следует выделить в отдельную дирректорию с именем документа. Сам же файл документа следует назвать main.md. Графику следует помещать в папку _pic, файлы в _files.

Служебные файлы

SUMMRY.md - файл структуры оглавления, при добавлении страницы следует обязательно сделать ссылку на нее в оглавлении, иначе не будут работать ссылки на нее с других страниц документов. Переименовывать не следует.

README.md - данный файл используется как описание репозитария на GitBook и GitHub. Переименовывать не следует.

book.json - конфигурация плагинов GitBook (используется при сборке книги после push`a на сервер). Переименовывать и редактировать не следует