Documentation revamp (#49)

* add readme for decision docs

* more detailed readme

* fix contributing.md

* add intro to contributing md

* add github contributing guidelines

* change emoji

* add how to reach out

* move reach out, suggestions and questions to readme

* add information about decision docs and primitives in contributing.md

* add information about how to add tests blog

contributing.md

@@ -0,0 +1,99 @@
+# Contributing Guide
+
+We welcome contributions from anyone, even if you are new to open source. We will help you with any technical issues and help improve your contribution so that it can be merged.
+
+Every small change of refactoring, documentation, code commenting, questions, suggestions, adding a test, adding a primitive makes the project better and will help making Dyalog APL bug free. 𓆣
+
+## Basic Setup
+
+To contribute, make sure your set up:
+
+- Your username + email
+- Your ~/.gitconfig
+- Dyalog (preferably version >18.2 unicode)
+
+### Fork ullu
+
+Step 1. Create a fork of the project repository
+
+Step 2. Clone the project repository from GitHub and set up your remote repository
+
+```
+git clone https://github.com/dyalog/ullu.git
+cd ullu
+git remote add REMOTE_NAME https://github.com/YOUR_GITHUB_USERNAME/ullu.git
+```
+
+`REMOTE_NAME` is the name of your remote repository and could be any name you like, for example your first name.
+
+`YOUR_GITHUB_USERNAME` is your user name on GitHub and should be part of your account path.
+
+You can use `git remote -v` to check if the new remote is set up correctly.
+
+## Sending a Pull Request/Merge Request
+
+Step 1. Create a new branch
+
+```
+git checkout -b fix1
+```
+
+Step 2. Make changes in relevant file(s)
+Step 3. Commit the changes:
+
+```
+git add FILE1 (FILE2 ...)
+git commit -m "YOUR_COMMIT_MESSAGE"
+```
+
+[Here](https://cbea.ms/git-commit/) are some great tips on writing good commit messages.
+
+Step 4. Check to ensure that your changes look good
+```
+git log --pretty=oneline --graph --decorate --all
+```
+
+Step 5. Send the pull request
+```
+git push REMOTE_NAME fix1
+```
+
+The command will push the new branch fix1 into your remote repository REMOTE_NAME that you created earlier. Additionally, it will also display a link that you can click on to open the new pull request. After clicking on the link, write a title and a concise description then click the “Create” button.
+
+Yay you are now all set. ٩(ˊᗜˋ*)و
+
+## Contributing Code
+
+### Adding a primitive
+
+A primitive is a built-in function or operator which is a core part of the language. It is represented by a glyph, which it may share with another primitive. More information [here](https://aplwiki.com/wiki/Primitive)
+
+Ullu tests the primitives one-by-one covering all the code written in the sources of Dyalog APL, all possible cases including edge cases and all types of inputs it can receive. 
+
+<!-- how to initialize the test files -->
+
+<!-- demo for a primitive (blog) -->
+A workflow demonstration blog on how to write tests is upcomming. Progress can be tracked [here](https://github.com/Dyalog/ullu/issues/50)
+
+<!-- ### Adding a test -->
+
+<!-- types of test cases -->
+
+## Contributing Docs
+
+### Decision docs
+
+<!-- what it is -->
+Decision Docs are records detailing key decisions, fostering transparency and aiding future collaboration by providing a structured account of the decision-making process. Documentation about why certain decisions were taken in the codebase, it basically explains the mindset of the developer writing the tests and it also documents all the anomalies in the codebase.
+
+It can be found [here](https://github.com/Dyalog/ullu/tree/docs-revamp/docs/decision)
+
+<!-- how to write -->
+In the decision docs, you need to mention the types of test cases included in the tests, description of all the variations of the tests and all the edge cases that were faced/handled. It needs to have all the information that a person in the future would need to expand the same tests or write new related ones. All the decisions taken while writing the tests.
+
+<!-- example -->
+Decision docs for the primitive Magnitude are a good example of this. It can be found [here](https://github.com/Dyalog/ullu/blob/docs-revamp/docs/decision/primitive-functions/scalar-monadic.md#magnitude-rydocs)
+
+---
+
+Note: By submitting a PR you agree to license your contribution under the ullu’s MIT [license](https://github.com/Dyalog/ullu/blob/main/LICENSE) unless explicitly noted otherwise.

docs/decision/readme.md

@@ -0,0 +1,3 @@
+# Decision Docs
+
+Decision Docs are records detailing key decisions, fostering transparency and aiding future collaboration by providing a structured account of the decision-making process. Documentation about why certain decisions were taken in the codebase, it basically explains the mindset of the developer writing the tests and it also documents all the anomalies in the codebase.

readme.md

@@ -8,20 +8,20 @@
 
 ## 🤔 What is ullu?
 
-Ullu is a QA for DyalogAPL (can be used to test any APL) which tests specifically the functionality of primitives.
+Ullu is a QA for DyalogAPL (can be used to test any APL ideally) which tests specifically the functionality of primitives one-by-one. The main focus of this test suite is to find bugs, irregularities, edge cases and code coverage.  
 
 ## 🎿 Coverage
 
 ### 💪  Available Tests
 - floor (monadic ⌊)
-- index of (dyadic ⍳)
 - magnitude (monadic |)
-- membership (dyadic ∊)
 - residue (dyadic |)
+- unique (monadic ∪)
 
 ### 🧱 Under progress
-- unique (monadic ∪)
-- unique mask (monadic ≠)
+- index of (dyadic ⍳) (Not tested for coverage)
+- membership (dyadic ∊) (Not tested for coverage)
+- unique mask (monadic ≠) (Next Up with #44)
 
 ## ✍ The name
 
@@ -31,6 +31,8 @@ Just as the owl represents both wisdom and foolishness the QA also has a dual na
 
 ## ⬇ Usage
 
+You can use ullu in a dyalog session on any supported operating system.
+
 ### Quick Run
 
 Run tests using dyalogscript:
@@ -73,6 +75,18 @@ or
 unittest.RunTests tests.membership
 ```
 
+### 🔗 More documentation
+
+- [Contributing.md](https://github.com/Dyalog/ullu/blob/main/contributing.md): Guide on how to contribute to the codebase
+- [Decision docs](https://github.com/Dyalog/ullu/tree/main/docs/decision): Explains the decisions taken with each step of the codebase and also documents anomalies for future users.
+
+
+### 🔗 Suggestions/Questions
+
+Feel free to open GitHub issues for any questions, suggestions or features requests
+
+If you want to reach out, please email `aarush[at]dyalog.com`
+
 <!-- ### 🔗 References -->
 
 ## ⚖ Licence