diff --git a/docs/interop.md b/docs/interop.md
new file mode 100644
index 0000000..45ae1bc
--- /dev/null
+++ b/docs/interop.md
@@ -0,0 +1,13 @@
+# interoperability
+api needs to facilitate easy interoperability with other languages and tools,
+for that certain considerations are taken:
+
+* number of public api calls is kept at the minimum
+* procedure signatures can only use basic types, no aggregates, with exception of Vec/Matrix types and alike,
+  with no expectation on new additions (see [/include/twn_types.h](/include/twn_types.h))
+* optionals can be expressed via pointer passage of value primitives, with NULL expressive default, but they should be immutable
+* opaque types are passed around as pointers
+* when mutation on input is done, - it shouldn't be achieved from a mutable pointer, but return value
+* module prefix is used for namespacing, actual symbols come after the prefix (`module_symbol`)
+* symbols should not contain letters at the start nor after the namespace prefix
+* [/include/twn_api.json](/include/twn_api.json) file is hand-kept with a schema to aid automatic binding generation and other tooling
diff --git a/docs/interop.txt b/docs/interop.txt
deleted file mode 100644
index fd6101f..0000000
--- a/docs/interop.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-api needs to facilitate easy interoperability with other languages and tools,
-for that certain steps are taken:
-
-* number of public api calls is kept at the minimum
-* procedure signatures can only use basic types, no aggregates, with exception of Vec/Matrix types and alike,
-  with no expectation on new additions (see /include/twn_types.h)
-* optionals can be expressed via pointer passage of value primitives, with NULL expressive default, but they should be immutable
-* /include/twn_game_api.json file is hand-kept with a schema to aid automatic generation and other tooling
-
-one of main inspirations for that is opengl model