📘 Read.me – Adding content to improve F5 clarity, and project structure details

README.md

@@ -1,40 +1,80 @@
-# Tina.io website
+### Hi Legends 👋
+# <p align="center">Tina.io – the Website for [TinaCMS](https://github.com/tinacms/tinacms)</p>
+
+Source code for the tina.io website, including the TinaCMS documentation and blog.
 
-Source code for the [tina.io](https://tina.io) website.
+Found a bug? Create a PBI and we'll look into it.
 
-## Development
 
-```
+## 🧿 Vision
+
+Make a wesbite to communicate the awesomeness of TinaCMS.
+
+## 🛠️ Tech Stack
+
+Static web application built with...
+
+- [React](https://reactjs.org/)
+- [Next.js](https://nextjs.org/)
+- [TypeScript](https://www.typescriptlang.org/)
+- [Tailwind CSS](https://tailwindcss.com/)
+
+- and of course... [TinaCMS](https://github.com/tinacms/tinacms)! 🦙
+
+Hosting and deployment...
+
+- GitHub and [Vercel](https://vercel.com/)
+
+<br>
+
+## 🛠️ Dependency Installation + Setup
+
+We're using [pnpm](https://pnpm.io/) as the package manager for node.
+
+```bash
 cp .env.example .env
 pnpm i
+```
+
+**Note**: Python is required for gyp – install [python](https://www.python.org/downloads/) and if necessary (newer python versions) the [setup tools](https://stackoverflow.com/a/77638742).
+
+<br>
+
+## 🧑🏻‍💻 Running the Project
+```bash
 pnpm dev
 ```
+This will spin up the react/Next project locally, running on [localhost:3000](http://localhost:3000) (react app) and [localhost:4001](http://localhost:4001/graphql) (playground for testing graphql against the Tina datalayer).
 
-## Vision
-Make a wesbite to communicate the awesomeness of TinaCMS
+<br>
 
-## Tech Stack
-- NextJS
-- TinaCMS
-- GitHub
-- Markdown
+## 📜 Contribution Expectations
 
+We welcome contributions to improve the Tina.io experience!
 
-### Testing Local TinaCMS Changes
+1. **Fork the Repo**: Work on your own fork to avoid conflicts.
+1. **Branching**: Use `feature/your-feature-name` or `bugfix/your-bugfix-name` for changes.
+1. **Using TinaCMS**: For content changes (e.g., docs), use visual editing with TinaCMS locally (e.g., http://localhost:3000/admin).
+1. **Commits**: Write clear, descriptive messages. Break large changes into multiple commits.
+1. **Code Quality**:
+   - Use Tailwind over inline CSS or styled components.
+   - Follow DRY principles and refactor reusable code.
+   - Comment on calculations or workarounds, and open issues for any technical debt.
+1. **Pull Requests**:
+   - Reference related issues and include screenshots for UI changes.
+   - If no issue exists, create one and link it.
+   - Commit the generated `tina-lock.json` file, and rerun the project locally after merging to update it.
+1. **Review Process**:
+   - Due to Vercel deployment issues, maintainers will recreate your changes on a new branch to test before approval.
 
-If you have the **tinacms** repository cloned locally you can use it when running **tina.io**:
+Cheers! 🦙
 
-```
-TINA=../path/to/tinacms pnpm dev
-```
+## Not Familiar with Tina?
 
-You can also specify which packages you want to watch:
+We've put together a simple explanation of the project directory – in [_docs/Directory-Structure](_docs/Directory-Structure.md).
 
-```
-TINA=../path/to/tinacms TINA_WATCH=@tinacms/forms,react-tinacms-inline
-```
+This should give you an idea of how it all fits into the project.
+
+Additionally, the Tina [docs](https://tina.io/docs/) contains the usage details for development with Tina.
 
-> ### Warning
->
-> This will only work for packages loaded by webpack. That means that environments which don't use
-> webpack (i.e. SSR builds) will not use this alias.
+<br>

_docs/Definition-of-Done.md

@@ -0,0 +1,22 @@
+# Definition Of Done
+
+An issue in this repository can be closed (considered done) for...
+
+### Code + Content Changes
+
+1. Code compiles and change makes sense for the issue. All issue tasks have been ticked.
+1. When the latest commit has been manually tested against a preview deployment.
+1. When the code has been reviewed by a project maintainer.
+
+1. Code has been deployed to production.
+1. Any bugs or technical debt that arise from the issue have been logged in a PBI that links to this code change.
+1. Issue had been closed with a closing comment added describing solution or linking changed pages.
+
+
+### Other Tasks
+
+1. All issue tasks have been ticked.
+
+1. PO has signed off on the task.
+1. Issue had been closed with a closing comment added describing solution or last status.
+1. Done email has been sent (if required).

_docs/Definition-of-Ready.md

@@ -0,0 +1,10 @@
+# Definition Of Ready
+
+Prior to being actioned, an issue in this repository should at minimum contain...
+
+- Enough detail for the team (or future teams) to action
+- Effort assigned (we use the [SSW recomendation](https://www.ssw.com.au/rules/estimating-do-you-know-how-to-size-user-stories-effectively/) for business and effort value estimates).
+
+    ...possible efforts are 0, 1, 2, 4, 8, 16 with each point of effort corresponding to a quarter day (~2 hours). Larger tasks should be done over multiple PBIs.
+- We're not using business values for this project. 
+- Assigned to `backlog ready` with PO approval.

_docs/Directory-Structure.md

@@ -0,0 +1,50 @@
+# 🏗️ Directory Structure
+
+Last updated: 26/09/2024
+
+```
+.
+├── components/
+│   ├── DocumentNavigation/
+│   │   └── ... various navigation menu components for the docs
+│   ├── layout/
+│   │   └── ... wrappers for site pages
+│   ├── blocks/
+│   │   ├── ... Tina block-editing components and schemas
+│   │   └── ... 🦙 https://tina.io/docs/editing/blocks/ 🦙 
+│   ├── tinaMarkdownComponents/
+│   │   ├── ... Rich-Text styling and embedded components
+│   │   └── ... 🦙 https://tina.io/docs/editing/markdown/ 🦙
+│   ├── toc/
+│   │   ├── ... contains docs table of contents (toc) schema
+│   │   └── ... generated toc component from doc headings
+│   ├── ui/
+│   │   └── ... re-usable utility components
+│   ├── styles/
+│   │   └── ... mix of styling code, TODO: standardise this
+│   └── ➕
+├── content/
+│   └── ... 🦙 🦙 🦙 (tina-managed site content)
+├── data-api/ and indices/
+│   └── ... related to algolia and content searching
+├── pages/
+│   └── ... 🖥️ nextjs page router 🖥️
+├── public/
+│   └── ... assets
+├── rss/
+│   └── ... rss generation (SEO or other reasons)
+├── scripts/
+│   ├── content-auditor/
+│   │   ├── ... local AI audit script for /content
+│   │   └── ... 🦙 https://ollama.com/ - unafilliated llama related software 🦙
+│   └── ➕
+├── styles/ (tailwind config)
+├── tina/
+│   ├── collectionsSchema/
+│   │   ├── ... Tina schema definitions (other than block templates)
+│   │   └── ... 🦙 https://tina.io/docs/reference/schema/ 🦙
+│   └── ➕
+├── utils/
+│   └── ... function definitions
+└── ... project config
+```

components/DocumentationNavigation/DocsHeaderNav.tsx

@@ -1,7 +1,7 @@
 import React from 'react'
+import data from '../../content/docs-navigation.json'
 import { LinkButton } from '../ui'
 import { DynamicLink } from '../ui/DynamicLink'
-import data from '../../content/docs-navigation.json'
 
 export const DocsHeaderNav = () => {
   return (