Как правильно документировать пакет на Github Open Source?
Всем привет. Есть код на php, который хочу вынести в библиотеку для общего доступа. С кодом и пакетом все понятно. Но сейчас мне нужно написать документацию по использованию этого кода да и в целом проекта. Поизучал несколько репозиториев symfony других библиотек. Везде все по разному и у меня остались вопросы:
1. README.md
Какая структура должна быть в этом файле? Что важно поместить сюда, а что лучше вынести в папку docs? Какие ключевые заголовки и стандарты есть по этому файлу? Везде делают по разному. Некоторые все питают в README.md, в том числе и версии. Например, хорошо если в документации есть иконки с количеством загрузки и тому подобного.
2. Какие ещё файлы нужно добавлять в пакете?
Помимо README.md встречаются и другие файлы. Например, CHANGELOG.md. Опять же кто-то версии пишет в README.
3. Какая структура папки docs?
Замечал, что некоторые файлы в данной папке имеют номера вначале названия. Кто-то их пишет без названий. У кого-то есть подпапка example у кого-то её нет. Как правильно здесь все выстроить?
4. Что описывать и как?
Документация это не поэма. Поэтому, документация должна быть краткой и содержательной. Но у всех разное понимание и восприимчивость. Для кого о будет понятно пару строк, а кому-то расписывать на страницу. Что обычно описывают в файлах документации?
5. Есть ли стандарты?
Документация придумана давно. Поэтому, наверняка уже есть какие-то стандарты по правильному оформлению, а так же написание документации. Поделитесь!
Понимаю, некоторые вопросы абсурдные, но хотелось бы разобраться в этом вопросе. Так же прошу поделиться своими наработками по разработке документации. Как вы разрабатываете доку для пакета. Если есть, то с примерами или шаблонами, но которые равняетесь.
Если есть какие ещё нюансы по разработке документации, фишки, лайфхаки, инструменты, сервисы по разработке и генерации документации - тоже буду раз их посмотреть и услышать.
