Для подробного описания шаблона используйте файл шаблон.md. Применяйте markdown-разметку или html-разметку. Описание будет выведено в нижней части окна редактирования.
Файл описания можно переместить в подпапку с именем, совпадающим с именем шаблона. Например для шаблона shop можно применять любой из этих файлов:
Кстати, туда же в папку shop помещайте CHANGELOG.txt и TODO.txt, понятно для чего.
Если речь идет об отдельном шаблоне, то по созданию документации всё понятно – вы просто пишите файл .md. Желательно также сделать краткое описание шаблона в файле .tdd.
Как же создавать документацию для больших комплектов шаблонов с многоуровневой вложенностью блоков? Здесь принцип остается тем же – вы так же пишите описания шаблонов в файлы .md. Нужно только знать, как правильно пользоваться системой этих описаний шаблонов.
Во-первых, в случае больших комплектов шаблонов, все файлы и папки лучше поместить в одну папку (shop). Никаких головных шаблонов снаружи этой папки лучше не создавать. Это вообще-то, будет и неуместным, так как интернет-магазин состоит из четырех различных разделов, головные шаблоны которых назначаются на разных страницах. Это такие шаблоны: catalog, order, client, admin.
Для каждого из этих головных шаблонов создаем файл .md, в котором, кроме собственно описания шаблона, необходимо написать инструкцию по назначению шаблонов для вложенных блоков.
Вначале создается каталог товаров, путем назначения на любой странице головного шаблона catalog. После назначения этого шаблона пользователь должен открыть окно редактирования этого блока и посмотреть инструкцию по назначению шаблонов для вложенных блоков (как правило, многие шаблоны будут уже назначены автоматически).
В свою очередь, для каждого вложенного шаблона нужно аналогично написать инструкции по назначению его дочерних шаблонов. Таким образом можно дойти до самого глубокого по вложенности шаблона.
Кроме файлов .md, рекомендуется создавать файл README.txt, где приводить общее описание комплекта и давать начальные инструкции по его головным шаблонам.