Где хранить документацию и вспомогательные файлы проекта?

#git #github #документация

Где хранить документацию и вспомогательные файлы, которые не относятся к коду, например,
скриншоты для README.md?

По скриншотам нашел два ответа на enSO:


How to add screenshot to READMEs in github repository ?
Add images to README.md on GitHub


Но там больше затрагивается проблема оформления README.md через Markdown. Меня же
интересуют лучшие практики для хранения вспомогательных данных. Какое место выбрать
для хранения? Отдельная ветка или репозиторий? Как использовать эти вспомогательные данные?

Пока вижу для себя следующее решение. Создаю в проекте ветку с вспомогательными данными
и кладу туда скриншоты, а к ним уже обращаюсь из файла README.md.

Для документации ситуация аналогична; думаю, пока проект небольшой, доки могут храниться
в одном репозитории.

Сам сейчас использую GitLab/GitHub.

Поделитесь, пожалуйста, своим опытом.
    

Ответы

Ответ 1

Наверное самое лучшее решение иметь confluence, а так же хранить проект либо на bitbuckete(jira),
либо tfs, если windows разработка, там очень мощные возможности вести документацию
и хранить  вспомогательные файлы


Ответ 2

Хранить документацию (скриншоты и диаграммы относятся к ней) лучше в той же ветке,
что и код. Например, в отдельно директории в корне проекта диретория docs. Чем "ближе"
документация к коду, тем меньше вероятность расхождения кода и документации.

Для многих фреймворков и систем сборки существуют правила хранение документации к
коду. Например, maven ожидает, что у вас будет директория site и в ней будет документация
и тогда maven сможет её отформатировать и загрузить на сайт.

Так же многие фреймворки могут выдавать ошибки, если к коду отсутствует документация.

Существуют различные плагины к системам сборки которые помогают создавать, проверять
и публиковать документацию. Например, AsciiDoctor имеет плагины для различных систем
сборки.


Ответ 3

Если документация - это отдельный проект, который разрабатывается отдельными людьми
и никак реально не связан с кодом -- то стоит завести отдельный репозиторий. 

Так например делает github, создавая под wiki вполне самостоятельный репозиторий,
которым можно отдельно управлять и вести историю изменений.


Ответ 4

1. Мнение

Подход, который мне больше всего нравится — создание для документации отдельного
сайта. Так делают разработчики Open Source проектов, которые мне представляются наиболее
серьёзными и значимыми.

Это можно осуществить бесплатно, если пользоваться генераторами статических сайтов.



2. Примеры документаций, сделанных при помощи средств, помогающих размещать их на
отдельных сайтах


MkDocs — пример





ReadTheDocs — пример





Sphinx — некоторые проекты, использующие Sphinx; пример:






3. Аргументы

Основной аргумент — ограничения хостингов для размещения HTML-сайтов ниже тех, с
которыми приходится иметь дело при размещении документации на BitBucket, GitHub (но
не с BitBucket Pages, GitHub Pages), GitLab и аналогичных ресурсах.

Положим, если Вы решили разместить документацию в README.MD и прочих .md файлах на
GitHub:

3.1 Доступно


Всё, что позволено разметкой Markdown,

но

не то что в Markdown достигается средствами HTML, а не самого Markdown.

Упрощённо говоря, Вы можете использовать чёрный по белому текст, изображения, таблицы,
но не более того.


3.2 Недоступно


Не получится использовать JavaScript: Вы не сможете использовать JQuery-плагины,
сделать удобное меню на Bootstrap для удобства перемещения пользователей по Вашей документации,
вынуждены будете отказывать себе в мелочах вроде кастомного скроллбара и т. д.
Не получится встроить видео без перехода на другую страницу для его просмотра.




4. Особенности генераторов статических сайтов


Писать сайты прямо в HTML не очень удобно. К счастью, одной из функций генераторов
статических сайтов является рендеринг текста, написанного в удобной для Вас разметке,
как то Markdown или reStructuredText, непосредственно в HTML.
Возможность интеграции с инструментами для сборки: я, допустим, использую Pelican
+ Grunt + CoffeeScript + Stylus.
Существуют генераторы, специально ориентированные для написания документаций к проектам.
Некоторые примеры приведены в разделе 2. Притом если Вас устраивают уже имеющиеся темы,
можно использовать их, а не писать с нуля.




5. Дополнительные ссылки


Static Site Generators — бесплатная книга издательства O'Reilly,
Working with Static sites,
Альтернативы MkDocs на AlternativeTo.Net.