diff --git a/README.md b/README.md
index ed0329f..4bce930 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,38 @@
 # Documentation Template
+
+diplodoc documentation template
+
+features:
+
+- initial project structure
+- dev server with hot reload
+- codespaces support
+- vscode tutorial via code tours
+
+## usage
+
+### run locally by cloning repo:
+
+```
+> git clone git@github.com:diplodoc-platform/documentation-template.git
+
+> cd documentation-template
+
+> npm start
+
+> listening on 0.0.0.0:8000
+
+```
+now you have development server with hot reload runing and serving built documentation on `0.0.0.0:8000`
+
+### github codespaces
+
+press Use this template -> Open in a codespace
+
+![open in a codespace](images/open-in-a-codespace.jpeg)
+
+wait for the development server startup
+
+enjoy developing documentation with html result preview in split view
+
+![codespaces project](images/codespaces-project.jpeg)
diff --git a/images/codespaces-project.jpeg b/images/codespaces-project.jpeg
new file mode 100644
index 0000000..67189dd
Binary files /dev/null and b/images/codespaces-project.jpeg differ
diff --git a/images/open-in-a-codespace.jpeg b/images/open-in-a-codespace.jpeg
new file mode 100644
index 0000000..89c78ca
Binary files /dev/null and b/images/open-in-a-codespace.jpeg differ