Overview and design documentation should not be inside code as it makes code less readable and greatly increases cognitive load when browsing files. However, it should also not be distant from code as that minimizes the incentive to write documentation and to read documentation.
As Soul Engine is a folder based project as there is no set IDE to manage a project, it follows that documentation can rest inside the source tree. Documentation is always visible for contribution and for remembering while being one step removed from actual coding.
A DESIGN.rst file should be placed where design or usage situation is brought forth by a directory name and the directory's local files, such as the root of a module
Overview and design documentation should not be inside code as it makes code less readable and greatly increases cognitive load when browsing files. However, it should also not be distant from code as that minimizes the incentive to write documentation and to read documentation.
As
Soul Engineis a folder based project as there is no set IDE to manage a project, it follows that documentation can rest inside the source tree. Documentation is always visible for contribution and for remembering while being one step removed from actual coding.A
DESIGN.rstfile should be placed where design or usage situation is brought forth by a directory name and the directory's local files, such as the root of a module