Approach to documentation - worldscapes/engine GitHub Wiki

After Arkanoid POC it became obvious that the Engine lacks documentation while existing documentation is hard to maintain.

To keep everything clear and updated, it's important to follow a mindful approach when documenting the Engine.

The following steps can help with this problem:

1. Differentiate abstract conceptual documentation against implementation documentation.
2. Keep conceptual documentation short and concise.
   The main goal for it is to cover principles, targets, ideas, and approaches. They do not change often but allow us to make correct and mindful decisions.
3. Store implementation documentation where the code which it describes is.
   It allows to easily distribute, find, maintain, and use it together with code navigation.
4. Include environment / functionality setup guidance in implementation documentation.