Эксперт Джон Джаго назвал два проекта с открытым исходным кодом, у которых разработчиками собрана и представлена исключительная техническая документация, включая высокую детализацию кода и архитектуры. Это esbuild и Redis.

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

Преимущества хорошей документации:

• экономия времени на работы с кодом, особенно если работаете командно, не нужно дополнительно объяснять всю кодовую базу каждому разработчику;

• такой проект с открытым исходным кодом с большей вероятностью получит поддержку со стороны и, следовательно, продолжит своё существование даже после того, как автор больше не сможет его поддерживать;

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

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

• это помогает структурировать ваше мышление и выявить недостатки. Когда вы пишете, вам необходимо чётко обдумывать и записывать то, что вы думаете, и это выявляет потенциальные проблемы.