docs.a374.ru

УПРАВЛЕНИЕ ДОКУМЕНТАЦИЕЙ

img

Markdown files

MARKDOWN ДОКУМЕНТАЦИЯ

Простая документация, которая не описывает код, ведётся в файлах Markdown. Такую документацию нужно вести самым простым способом. Размещать же такую документацию лучше на GitHub. Этот документация пример такого размещения. Редактируется все в одной папке в одном редакторе.

Документация размещается таким способом чтобы она максимальна была бы доступна и читаема в одном репозитории на сервере GitHub в любом отделе включая подмодуль Wiki, также на web-сайте GitHub Pages, также на сторонем сайте публикации. Один раз публикуем и в трёх местах получаем отличный результат. Эта документация размещена на GitHub-Pages и ранее была также размещена на сервере ReadTheDocs, и вы также можете при необходимости воспользоваться этим сервисом. Также, она просто читается в самом РЕПОЗИТОРИИ на github и имеет рабочие ссылки во всех проектах, включая и картинки.

Если вам понадобиться подключить GitHub-WIKI, тогда подключите модуль wiki добавив его в основной проект и перенесите туда содержимое директории docs. Важно помнить, что вики парсит только Markdown разметку и все настройки yaml или Jekyll будут показаны как есть. Сам GitHub-WIKI это независимый модуль, который никак не связан с основным проектом, поэтому в нем можно смело редактировать доки. Но !!! GitHub-WIKI не должен являться исходником документации. Переносити тексты в него, а не из него. Только Uploads to wiki.

Исключением является ссылка …на главную, она не работает только в репозитории в файлах.

ЧТО НЕ НУЖНО ДЕЛАТЬ

  1. Не нужно подключать к документации на GitHub Jekiyll, GitHub автоматом парсит файлы Markdown и может применять к ним настройки yaml.

  2. Не нужно использовать файл _config.yaml.

  3. Не нужно генерировать навигацию Jekyll. Вся навигация отлично генерируется сервисом ReadTheDocs.

  4. Не нужно использовать разметку yaml в файле readme.md в директории docs.

  5. Не наращивайте деревьев, за большим садом сложно следить. Много веток, много листьев с кодом и т.д..

КОДОВАЯ ДОКУМЕНТАЦИЯ

Документация по коду получится вести только с использованием генераторов документации для выбранного языка программирования.

Лучше всего вести документирование проекта прямо в исходниках без генерации доков. Если понадобится документация по коду можно позже привлечь сборщик и собрать уже подготовленную документацию. Документация кода требует очень частых правок и много времени, поэтому целесообразно и очень выгодно документировать локально в самом коде.

КАРТИНКИ ДОКОВ

Снабжайте документацию Markdown любыми картинками. Самое главное память взгляда. Ум устает от символов и очень хорошо запоминает картинки и общие виды. Картинки должны быть расположены, желательно, на отдельном надежном сервере. Сама документация никогда не должна располагаться на только платном ресурсе. Самый лучший вариант комбинированные услуги размещения материалов.

Скидываешь картинки на сервер в безконечную кучу и всегда под рукой адрес кучи + имя файла. Таким образом можно легко разрабатывать в любом месте и редакторе независимо от архитектуры проекта и его реализации на хостинге. Это удобно.

УКАЗАТЕЛЬ ДОКОВ

Указатель места расположения ресурсов служит доменное имя. Домен не должен располагаться на ресурсе материалов. Домен должен работать и настраиваться как отдельный указатель на отдельном сервере и не более того. Это просто нужный вам или ненужный удобный указатель.

ЕЩЕ ВАЖНОЕ

При размещении документации и ее подготовки к публикации нужно учитывать корректность отображения ее при авто переводе, мобильном авто переводе и просто удобо-читаемости на мелких гаджетах, также на старых гаджетах и другие настройки, которые обычно все сразу не учтешь, а потом очень сложно что-то внедрить или переделывать. Это не настройки, а предусмотрительность. Нужно заранее проверять как сервер взаимодействует с разными веб-сервисами и браузерными популярными и не очень – расширениями. Иногда вид бывает обманчив очень.

Продуманное вначале сильно облегчает будущее продуманному программисту.



img


     
← назад 🔝 далее →