add diataxis info to docs readme (pyscript#548)

fpliger · web-flow · commit 96a73e31f344 · 2022-06-24T17:06:47.000-03:00
* add loca build info to htmlserve

* add info about diataxis to the docs/readme

* add diataxis img
diff --git a/docs/Makefile b/docs/Makefile
@@ -31,7 +31,8 @@ shell:
 	@echo 'conda activate $(env)'
 
 htmlserve:
-	python -m http.server -d "$(BUILDDIR)/html/"
+	@echo 'visit docs at http://localhost:8080'
+	python -m http.server -d "$(BUILDDIR)/html/" 8080
 
 livehtml:
 	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
@@ -9,6 +9,16 @@ Before you start contributing to the documentation, it's worthwhile to
 take a look at the general contributing guidelines for the PyScript project. You can find these guidelines here
 [Contributing Guidelines](https://github.com/pyscript/pyscript/blob/main/CONTRIBUTING.md)
 
+## Documentation Principles
+
+The PyScript documentation is based on a documentation framework called [Diátaxis](https://diataxis.fr/). This framework helps to solve the problem of structure in technical documentation and identifies four modes of documentation - **tutorials, how-to guides, technical reference and explanation**. Each one of these modes answers to a different user need, fulfils a different purpose and requires a different approach to its creation.
+
+The picture below gives a good visual representation of that separation of concerns:
+
+![pyodide-pyscript](./img/diataxis.png)
+
+So, please keep that in mind when contributing to the project documentation. For more information on, make sure to check [their website](https://diataxis.fr/).
+
 ### Setup
 
 The `docs` directory in the pyscript repository contains a
diff --git a/docs/img/diataxis.png b/docs/img/diataxis.png
