updating documentation (#330)

Author: Varun-Sethu

README.md

@@ -22,37 +22,17 @@ run:
 
 ## Environment Variables
 
-Please note that you have to add /Config/.env.dev and include the env secrets. Please contact `laurlala#1696`, `jumbo#9999` or `Mae#6758
-` on discord for these if you don't have them :)
+Please note that you have to add /Config/.env.dev and include the env secrets. Please contact `laurlala#1696`, `jumbo#9999` or `Mae#6758` on discord for these if you don't have them :)
 
 ## Postgres Instructions
-access interactive terminal by running `docker exec -it pg_container bash`
+Access interactive terminal by running `docker exec -it pg_container bash`
 now run this command `psql -d test_db -f infile` to load the dummy data we have prepared in ./postgres/infile
 or run `make pg`
 
 
-
-## Some Resources
-Our editor uses quite a few algorithms so below is a list of resources you can use to learn about them and hopefully contribute to the editor :)
- - [Differential Synchronisation Algorithm](https://neil.fraser.name/writing/sync/eng047-fraser.pdf)
- - [Myer's Difference Algorithm](http://www.xmailserver.org/diff2.pdf)
- - [A cool blog post](https://blog.jcoglan.com/2017/02/12/the-myers-diff-algorithm-part-1/)
- - [String Difference Strategies](https://neil.fraser.name/writing/diff/)
-
-
-
 ## FAQs:
-- Q: something is broken what to do?
-- A: run `make clean` then run `make dev-build` again, should fix it
-
-- Q: something is horibbly broken
-- A: manually remove all images in docker desktop GUI app and re-run `make dev-build` again
-
-- Q: it says I don't have docker installed, but I have already installed docker before
-- A: open your docker desktop app then re-run it
-
-- Q: it still doesnt work
-- A: google docker desktop WSL2 not detecting docker
+- Q: Something is broken what to do?
+- A: Run `make clean` then run `make dev-build` again, should fix it, if it is still broken then manually remove all images in the docker desktop GUI and re-run `make dev-build`.
 
-- Q: Docker is taking up alot of space how to remove?
-- A: docker is a ram/storage drainer but, you can remove useless volumes, run `docker volume prune`
+- Q: Something has gone wrong with Docker, where can I find docker resources?
+- A: Docker is rather well documented, check out the docker website: https://www.docker.com/ to try and resolve your issue.

backend/README.md

@@ -8,12 +8,33 @@ The backend folder contains all our backend code 🤯. Theres a few important fo
  - ### `endpoints/`
    - Contains all our HTTP handlers + methods for decorating those handlers, additionally provides methods for attaching handlers to a `http.ServeMux`
  - ### `editor/`
-   - Contains all the backend code for synchronisation (bit of a mess right now 😭). It is essentially just a big implementation for the differential sync algorithm and supports extension via the construction of `extensions`
+   - There are currently 3 different editor backends, once the OT backend is fully complete this will collapse down to just OT
+      - The OT folder contains our implementation of the operational transform algorithm, specifically Google WAVE OT
+      - The pessimistic editor is a lock based editor, instead of implementing an optimistic concurrency protocol it simply locks the editor while a conflicting client is using it
+      - The diffsync folder contains all the backend code for synchronisation (bit of a mess right now 😭). It is essentially just a big implementation for the differential sync algorithm and supports extension via the construction of `extensions`
    - The package allows multiple clients to be connected to the same document and ensures that each client sees the exact same document state (via a best effort diff + patch)
    - Currently only works on strings with no inheret structure but in the future will work on JSON documents too 😀 
- - ### `algorithms/`
-   - Mostly algorithms used by the editor such as Myer's string difference algorithm (glorified BFS tbh) and some prefix/suffix computation
  - ### `environment/` & `internal/`
    - Methods/packages that can be used to retrieve information about the current environment and other internal utilities 
  - ### `client`
    - WIP TypeScript implementation of client server for operational transform
+
+
+## Papers worth Reading
+Most of the complexity of the CMS backend is within the editor, to aid with your tickets we have accumilated a few great resources that are worth a read.
+  - [A survey of OT algorithms](https://www.researchgate.net/profile/Ajay-Khunteta-2/publication/45183356_A_Survey_on_Operational_Transformation_Algorithms_Challenges_Issues_and_Achievements/links/5b9b27dca6fdccd3cb533171/A-Survey-on-Operational-Transformation-Algorithms-Challenges-Issues-and-Achievements.pdf?origin=publication_detail)
+  - [The Jupiter Operational Transform Algorithm](https://lively-kernel.org/repository/webwerkstatt/projects/Collaboration/paper/Jupiter.pdf)
+  - [Google Wave OT (Multi-client single server OT)](https://svn.apache.org/repos/asf/incubator/wave/whitepapers/operational-transform/operational-transform.html)
+  - [Transformation algorithms for ordered n-ary trees](https://arxiv.org/pdf/1512.05949.pdf)
+  - [Differental Synchronisation](https://neil.fraser.name/writing/sync/eng047-fraser.pdf)
+
+## Language Documentation & Resources
+If this is your first time using Go then the following resources might be of some use:
+ - [2022 CSESoc Dev Go Workshop](https://drive.google.com/file/d/1zLJHkcktLFXKXs6MFNVmWyfVtTHq8ng8/view)
+ - [Unit testing in Go](https://www.digitalocean.com/community/tutorials/how-to-write-unit-tests-in-go-using-go-test-and-the-testing-package)
+    - [Interface mocking & gomock](https://itnext.io/how-to-write-better-unit-tests-in-go-using-mocks-4dd05e867b17)
+ - [Generic Programming in Go](https://go.dev/doc/tutorial/generics)
+ - [Concurrent Programming in Go](https://golangdocs.com/concurrency-in-golang)
+      - [Communicating Sequential Proceseses (Go's model of concurrency)](https://www.cs.cmu.edu/~crary/819-f09/Hoare78.pdf)
+          - It's not required but its a nice read
+ - [Godoc](https://go.dev/blog/godoc)