Эксперт Джон Джаго назвал два проекта с открытым исходным кодом, у которых разработчиками собрана и представлена исключительная техническая документация, включая высокую детализацию кода и архитектуры. Это esbuild и Redis.
По мнению Джаго, через файлы README, журналы изменений, архитектурные документы и комментарии к коду оба эти проекта объясняют свой дизайн таким образом, чтобы даже новичок может понять в кодовой базе, где что находится, как что-то делается и почему это делается именно так. Он порекомендовал разработчик, желающим лучше документировать свой код и архитектуру программного обеспечения, брать для примера эти проекты.
Преимущества хорошей документации:
экономия времени на работы с кодом, особенно если работаете командно, не нужно дополнительно объяснять всю кодовую базу каждому разработчику;
такой проект с открытым исходным кодом с большей вероятностью получит поддержку со стороны и, следовательно, продолжит своё существование даже после того, как автор больше не сможет его поддерживать;
прошлые ошибки и решения, которые подвергались сомнению, записаны, что не позволяет случайно повторно привести к проблеме, которую помогло решить прошлое решение;
приложение или библиотеку смогут использовать больше людей, поскольку меньшему количеству из них придётся во всем разбираться самостоятельно;
это помогает структурировать ваше мышление и выявить недостатки. Когда вы пишете, вам необходимо чётко обдумывать и записывать то, что вы думаете, и это выявляет потенциальные проблемы.
