feat(octo-contribution-docs): doc enhancements.

apps/octo-contribution-docs/docs/getting-started/getting-started.mdx

@@ -0,0 +1,74 @@
+---
+sidebar_position: 2
+title: Getting Started
+---
+
+import RootProjectStructure from './img/root-project-structure.png';
+
+## Requirements
+* **Node.js version** 16.0 or above.
+  * However, documentation websites `apps/*-docs` run on docusaurus,
+  which requires Node.js version to be `18.0` or above.
+  * So, **Node.js version `18.0`** or above is recommended.
+  * **`npm`** is the preferred package manager.
+* **IDE**
+  * Some developers prefer WebStorm, and some VSCode. There are other good options out there as well.
+  As long as the quality of commits meets the minimum standard, choice of IDE is of no concern.
+  * However, you will find more support for `WebStorm` in this documentation than any other IDE.
+
+## Project Structure
+<div class="layout_text_wrap_image">
+  <img src={RootProjectStructure} height="600" />
+  <div>
+    This is the [root](https://github.com/quadnix/octo) of the project.
+    Octo is a **monorepo**, i.e. all relevant files lives here.
+    And we use **`nx`** as the base library to facilitate the monorepo.
+
+    There is usually a huge debate between monorepo vs polyrepo, but after much consideration,
+    we felt having all code in one location outweighs most of the cons, and enforces common standards,
+    such as eslint, dictionary, and tsconfig, just to name a few.
+
+    The repository, at first glance, might look huge, but really is just a collection of small packages and apps,
+    all working independently, with their separate CICD pipelines and life cycles. They just live together,
+    like a little family they are.
+  </div>
+</div>
+
+<br />
+There is a lot to unpack here, but to get started here some important directories and files.
+* `apps`: is where we currently house all the documentation websites. They are `docusaurus` projects,
+i.e. React and Markdown files.
+* `packages` is where you will find Octo's distributable packages.
+  * `octo` is the base package.
+  * `octo-aws-cdk` is our AWS implementation of Octo.
+  * `octo-build` is the CLI tool to build Octo packages.
+* `.eslintrc.cjs`: is the base EsLint file. We use EsLint to enforce code linting.
+* `.prettierrc`: is the base Prettier file. We use Prettier to enforce code formatting.
+* `dictionary.dic`: is the spell check file.
+* Rest of the directories and files are not where you might spend much time.
+They are still tersely discussed later in this documentation.
+
+## Code Style & Guidelines
+* We follow [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) for the entire project.
+There are some minor differences where we deviate, but we expect to keep this list short.
+  * Column limit (120): our lines can be 120 character long as opposed to 80. This applies to all files in this project.
+* We keep anything sorted, where applicable, e.g. json files, object keys, configurations, etc.
+* We enforce a spell checker via EsLint. If the word is not recognized, it must have an entry in dictionary.dic
+
+## Documentation
+The role of documentation in any organization cannot be overstated, and we are no exception.
+We don't believe in great documentation, but we do expect to write documents consistently.
+The idea behind two sets of documentation is to capture the feature documentation,
+and also to capture the decisions leading up to the feature.
+
+If our contributors and developers feels "lost" and don't understand the changes they are about to commit,
+or how things work, then the documentation has failed them.
+
+Another important factor to consider while documenting, is to keep the context in perspective.
+The aim is to teach, and not to document.
+
+## Testing
+* We use `Jest` for writing tests. Unit, Integration, and E2E tests are supported.
+* `packages/*` are covered with tests. Documentation websites don't have tests.
+* We aim to test features, not lines of code. This might not mean 100% test coverage, which is okay.
+The idea is if the implementation of a feature changes, the tests (apart from mocks) don't change.

apps/octo-contribution-docs/docs/introduction/introduction.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 1
+title: Introduction
+---
+
+🎉 Welcome!!
+
+We are excited for you to be here, and thank you for considering to contribute to Octo.
+This documentation is dedicated to help you get started to make contributions and to not feel "lost".
+Here you might find information on contribution guidelines, tech stack, project structure, and much more.
+
+[//]: # (TODO: Insert Octo-Docs home page URL here.)
+:::tip
+Counterintuitively, you might not find much information on the internal workings of Octo here.
+This documentation is solely dedicated to help make contributions, not to learn Octo itself.
+<br />Though in order to make contributions, you need to understand the fundamentals of Octo,
+and so if you haven't already, you should check out.
+:::

apps/octo-contribution-docs/docs/root/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "<root>",
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
+}

apps/octo-contribution-docs/docs/root/git/git.md

@@ -0,0 +1,17 @@
+---
+sidebar_position: 1
+title: Git & GitHub
+---
+
+We use `Git` as our version control tool, and `GitHub` as the UI.
+
+## Commit Messages & PR
+Because we are a monorepo, the GitHub space is shared with multiple projects.
+We must take precaution while merging commits to ensure we understand which project we are talking about.
+
+Individual commit messages don't matter, since the PR you create will be "Squash and Merge".
+The `name` and `description` of the PR, however, must be properly formatted.
+
+## Issues, Features, & Bug Tracking
+* **TODO**: Create a TODO, as a comment, in code when the issue is small. It is something to remind yourself to do.
+* **GitHub Issue**: Create a GitHub issue for large features, and bugs. This is where discussions will happen.

apps/octo-contribution-docs/docs/root/husky/husky.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 2
+title: Husky & Git Hooks
+---
+
+[Husky](https://typicode.github.io/husky/) is a widely used tool to enforce Git hooks.
+Before we make any commit, husky enables us to run hooks that check the "correctness" of the commit.
+
+## Setup
+* Added to `package.json` under `devDependencies`, and under `scripts`.
+* For first time contributors, you need to run `npm run prepare` script to initialize husky.
+* A `<root>/.husky/_` directory is created with some husky scripts.
+* From this point, husky automagically runs and verifies your commits.
+
+:::danger
+You must try to never ignore the husky hooks. Always prefer to fix the issues first, or ask for help.
+
+To ignore verification, you can use the `no-verify` git option,
+> git commit --no-verify -m "commit message"
+:::
+
+## Configuration
+Our husky pre-commit hooks looks like,
+```shell
+#!/bin/sh
+
+npm run lint
+```
+i.e. we only run the `lint` script as our commit verification.

apps/octo-contribution-docs/docs/tutorial-basics/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Tutorial - Basics",
-  "position": 2,
+  "position": 4,
   "link": {
     "type": "generated-index",
     "description": "5 minutes to learn the most important Docusaurus concepts."

apps/octo-contribution-docs/src/css/custom.scss

@@ -28,3 +28,15 @@
   --ifm-color-primary-lightest: #4fddbf;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }
+
+.layout_text_wrap_image {
+  overflow: scroll;
+  img {
+    float: left;
+    margin: 5px;
+  }
+
+  div {
+    text-align: justify;
+  }
+}

dictionary.dic

@@ -51,7 +51,10 @@ mdx
 nacl
 nginx
 octo
+octo's
 octob
+polyrepo
+prettierrc
 proj
 promisify
 quadnix

docs/editor/vscode/settings.json

@@ -0,0 +1,17 @@
+{
+  "breadcrumbs.enabled": false,
+  "editor.fontFamily": "Office Code Pro",
+  "editor.fontSize": 14,
+  "editor.minimap.enabled": false,
+  "editor.rulers": [120],
+  "editor.scrollBeyondLastLine": false,
+  "editor.wordWrapColumn": 120,
+  "explorer.confirmDelete": false,
+  "extensions.ignoreRecommendations": true,
+  "files.insertFinalNewline": true,
+  "workbench.colorCustomizations": {
+    "editor.selectionBackground": "#ca5cb4",
+    "editor.selectionHighlightBackground": "#7F0C6B"
+  },
+  "workbench.tree.indent": 25
+}