added documentation for contributors

3 files changed, 85 insertions, 0 deletions

diff --git a/documentation/design.md b/documentation/DESIGN
index 2f90d84..2f90d84 100644
--- a/documentation/design.md
+++ b/documentation/DESIGN
diff --git a/documentation/STYLE b/documentation/STYLE
new file mode 100644
index 0000000..989b2b1
--- /dev/null
+++ b/documentation/STYLE
@@ -0,0 +1,58 @@
+When contributing to Sideros, you should take account of this
+style guide, which is mostly based on the Zig documentation
+style guide (https://ziglang.org/documentation/0.14.0/#Style-Guide).
+
+1. Avoid these words in type names:
+    - Value
+    - Data
+    - Context
+    - Manager
+    - utils, misc, or somebody's initials
+
+Everything is a value, all types are data, everything is context, all logic manages
+state. Nothing is communicated by using a word that applies to all types.
+Temptation to use "utilities", "miscellaneous", or somebody's initials is a failure
+to categorize, or more commonly, overcategorization. Such declarations can live at the
+root of a module that needs them with no namespace needed.
+
+2. Avoid Redundant Names in Fully-Qualified Namespaces
+Every declaration is assigned a fully qualified namespace by the compiler, creating a
+tree structure. Choose names based on the fully-qualified namespace, and avoid redundant
+name segments. For example, let's say you're writing a wrapping interface over WASM and
+you need to create a structure to hold WebAssembly values. If you are importing that
+file using `@import`, you will assign the code to a namespace, for example `wasm`.
+For this reason, you should avoid calling your WASM value interface something like
+`WasmValue`, because it will end up being used as `wasm.WasmValue`, just call it `Value`
+and the code will be overall more readable (`wasm.Value`).
+
+3. Whitespaces
+    - 4 spaces for indentation
+    - Open braces on same line, unless you need to wrap
+    - If a list of things is longer than 2, put each item
+      on its own row and excercise the ability to put an
+      extra comma at the end.
+    - Aim for 100 as line length.
+
+4. Names
+    - for types, use "TitleCase", unless it's a namespace,
+      in that case use "snake_case".
+    - if x is callable, and returns a `type`, then use "TitleCase"
+    - if x is callable, and doesn't return a `type`, use "camelCase"
+    - everything else should be "snake_case"
+Generally speaking, try to name things using easily understandable identifiers.
+This can mostly be done by just writing names as full english words, and avoiding
+acronyms and similar things. For example, prefer `time` over `t`, `speed` over `spd`
+and so on. Just by doing this most of the code wouldn't need comments, because the
+code will describe the logic by itself.
+
+5. Comments
+Comments should never explain how code works, but rather how code should be used.
+As stated in part 4, Zig has an explicit syntax allowing to write readable code,
+just by using extended words for names and thus, in-code comments, explaining
+how a specific part of code works, can be completely avoided.
+Documentation comments, instead, can be very useful when exposing types and
+functions, so that the behaviour of those can be easily read without going
+to look directly at the source code.
+The only exception is when the code logic can't be easily readable by
+humans for optimization reasons (bitwise magic, for example) and so
+in that case, in-code comments are allowed.
diff --git a/documentation/TODO b/documentation/TODO
new file mode 100644
index 0000000..77b4923
--- /dev/null
+++ b/documentation/TODO
@@ -0,0 +1,27 @@
+There are many things to implement in the game, here are listed some of them ranked by difficulty.
+
+EASY:
+
+- Writing a README file:
+Currently, there is no README file, also because the project doesn't have a clear outline yet.
+
+- Code refactoring:
+It's possible that sometimes code that doesn't conform to the style guidelines defined in STYLE will be pushed to the repository.
+Finding that code, and fixing it so that it conforms to the guidelines would be a nice way of getting your hands
+on the project for the first time and a big help to maintainers.
+
+- Documentation:
+One of the goals of the project is to be as welcoming as possible to new contributions, this can't really be the case without good
+documentation. Engine APIs, modding interfaces and modules of the code (rendering, vulkan, ecs, mods, ...) should be
+documented with text files in `documentation/` and in the documentation page of the website (TODO).
+
+MEDIUM:
+
+- Implement internal windowing system:
+The engine now uses GLFW to interface with the user's windowing system. But GLFW lacks flexibility and thus it might be better
+to implement an internal abstraction to create windows and receive input, based on xcb for X11, wayland-client for Wayland,
+Cocoa for MacOS and win32 for Windows.
+
+HARD:
+
+