Как правильно документировать пакет на Github Open Source?
============================================================

 Всем привет. Есть код на php, который хочу вынести в библиотеку для общего доступа. С кодом и пакетом все понятно. Но сейчас мне нужно написать документацию по использованию этого кода да и в целом проекта. Поизучал несколько репозиториев symfony других библиотек. Везде все по разному и у меня остались вопросы:  

  

**1. README.md**  

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

  

**2. Какие ещё файлы нужно добавлять в пакете?**  

Помимо README.md встречаются и другие файлы. Например, CHANGELOG.md. Опять же кто-то версии пишет в README.  

  

**3. Какая структура папки docs?**  

Замечал, что некоторые файлы в данной папке имеют номера вначале названия. Кто-то их пишет без названий. У кого-то есть подпапка example у кого-то её нет. Как правильно здесь все выстроить?  

  

**4. Что описывать и как?**  

Документация это не поэма. Поэтому, документация должна быть краткой и содержательной. Но у всех разное понимание и восприимчивость. Для кого о будет понятно пару строк, а кому-то расписывать на страницу. Что обычно описывают в файлах документации?  

  

**5. Есть ли стандарты?**  

Документация придумана давно. Поэтому, наверняка уже есть какие-то стандарты по правильному оформлению, а так же написание документации. Поделитесь!  

  

Понимаю, некоторые вопросы абсурдные, но хотелось бы разобраться в этом вопросе. Так же прошу поделиться своими наработками по разработке документации. Как вы разрабатываете доку для пакета. Если есть, то с примерами или шаблонами, но которые равняетесь.   

  

Если есть какие ещё нюансы по разработке документации, фишки, лайфхаки, инструменты, сервисы по разработке и генерации документации - тоже буду раз их посмотреть и услышать.   

  

Всем спасибо!) 

<https://opensource.guide/>