Update Documentation Guidelines

.github/pull_request_template.md

@@ -1,47 +1,19 @@
-<!--
-Thanks for contributing to Valkey GLIDE Documentation!
-
-Please make sure you are aware of our contributing guidelines [available
-here](https://github.com/valkey-io/valkey-glide/blob/main/CONTRIBUTING.md)
-
--->
-
-### Summary
+## Summary
 
 <!--
-Add a summary describing the changes
+Required. Summarize your changes in a short paragraph.
 -->
 
-### Issue link
-
-This Pull Request is linked to issue (URL): [REPLACE ME]
-
-### Content Changes
+### Related Issue
 
 <!--
-Outline the documentation updates, new pages, or content modifications included in this PR
--->
-
-### Implementation
+Link your PR to an appropriate issue here.
 
-<!--
-Describe the implementation details. Highlight key content changes and call out any areas where you want reviewers to pay extra attention
+If your PR is related to a code change in Valkey GLIDE, consider linking the PR to the appropriate issue.
 -->
 
-### Testing
+## Changes
 
 <!--
-Describe what tests have been conducted (e.g., build verification, link checking, visual review)
+Required. Please list the changes you have made, preferrably in bullet point forms.
 -->
-
-### Checklist
-
-Before submitting the PR make sure the following are checked:
-
-- [ ] This Pull Request is related to one issue.
-- [ ] Commit message has a detailed description of what changed and why.
-- [ ] All commits are signed off with `--signoff` flag.
-- [ ] `pnpm build` runs successfully.
-- [ ] Links have been checked for validity.
-- [ ] Destination branch is correct - main or release
-- [ ] Create merge commit if merging release branch into main, squash otherwise.

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to Valkey GLIDE Documentation
+
+Thank you for your interest in contributing to the [Valkey GLIDE documentation](https://glide.valkey.io)!
+
+This guide covers conceptual questions about writing documentation:
+
+- What kind of documentation should I write?
+- How should I write my documentation?
+
+For more technical instructions, like how to set up the environment, see our [Readme](/README.md).
+
+> **Note:** This repository is for the documentation site only. To contribute to the Valkey GLIDE client library itself, visit the [valkey-glide repository](https://github.com/valkey-io/valkey-glide/).
+
+## Language Agnostic Documentation
+
+The goal of Valkey GLIDE documentation is to be the single source of truth for the various Valkey GLIDE clients.
+
+When writing documentation, consider all client languages. In practice, this is easier than it sounds. Because clients share the same Rust core, they behave similarly and can share documentation, with language-specific code examples included when appropriate.
+
+## Adding Documentation For A New Feature
+
+Users come to the documentation to learn how to do something with GLIDE. When documenting a new feature, we recommend starting with a how-to guide. These are simpler to write and provide immediate value.
+
+How-to guides can include some conceptual explanation, but should stay focused on the "how". Lengthy explanations can be a distraction. If deeper context is needed, create a separate article in our Learn section instead.
+
+Guidelines for how-to articles:
+
+- The title should be an action (e.g., "Installing GLIDE", "Making Batch Commands").
+- The content shows the reader how to do something, often with code examples.
+- Some conceptual explanation is encouraged, but it should not be the focus.

README.md

@@ -1,34 +1,58 @@
 # Valkey GLIDE Documentation
 
-This repository host the source for the Valkey GLIDE documentation [site](https://glide.valkey.io).
+Welcome to the Valkey GLIDE documentation repository. The site is available at https://glide.valkey.io.
 
-## Technology
+> **Note:** This repository contains only the documentation of Valkey GLIDE.
+> To contribute to the Valkey GLIDE client library itself, visit [valkey-glide](https://github.com/valkey-io/valkey-glide/).
+
+## Overview
 
 The site is built with [Starlight](https://starlight.astro.build/), an Astro framework for building static documentation sites.
 
-The framework provides out-of-the-box features for building documentations like components, site search, navigation, and integrations with MDX files. It also leverages Astro's features like island architecture to build dynamic components.
+The framework provides out-of-the-box features for building documentations like UI components, site search, navigation, all using a Markdown like syntax. It also leverages Astro's features to build custom dynamic components.
+This aims to allow contributors to quickly add or edit existing pages using familiar Markdown syntax, while having the options to extend the site with modern Javascript components.
 
 ## Getting Started
 
-First clone the repo and install the required tools.
+You'll need the following installed:
 
-```bash
-git clone git@github.com:valkey-io/valkey-glide-docs.git
-
-# npm is fine too.
-brew install pnpm
-```
+- [Node.js](https://nodejs.org/) v20+
+- [pnpm](https://pnpm.io/) v10+ (`brew install pnpm` or `npm install -g pnpm`)
 
-Then install the dependencies
+Then clone the repo and install dependencies:
 
 ```bash
+git clone git@github.com:valkey-io/valkey-glide-docs.git
 cd ./valkey-glide-docs
 pnpm install
 ```
 
 For development, run `pnpm dev`. It will spin up a hot-loading development server to serve the documentation pages.
 
-### Link Checker
+### Making Changes
+
+Page content lives under `src/content/docs/` as `.mdx` files.
+
+- **Edit a page:** Modify the corresponding `.mdx` file.
+- **Add a new page:** Create a new `.mdx` file under `src/content/docs/`. Every file requires frontmatter:
+
+  ```mdx
+  ---
+  title: Your page title
+  ---
+
+  Your content follows...
+  ```
+
+- **Update the sidebar navigation:** Add your new page to `astro.config.mjs`.
+
+For a guidelines on how to write new articles, take a look at our [Contributing](/CONTRIBUTING.md) page.
+
+## Commit Requirements
+
+All commits must include the `--signoff` flag to certify the [Developer Certificate of Origin (DCO)](https://developercertificate.org/).
+
+## Link Checker
 
 We use [lychee](https://github.com/lycheeverse/lychee) to check for broken links. Configuration rules (exclusions) are defined in our `lychee.toml`.
 
@@ -44,20 +68,18 @@ Then to run the build and check links:
 pnpm build:check-links
 ```
 
-## Making Content Changes
+## Code Style & Formatting
 
-In general, page contents are located under `src/content/docs`.
+The project uses [Prettier](https://prettier.io/) for general formatting and [remark](https://github.com/remarkjs/remark) for MDX/Markdown linting. Configuration is in `.prettierrc.json` and `.remarkrc.json`.
 
-- For simple content update, change the appropriate `.mdx` files in the folder structure.
-- To create a new page, add a new `.mdx` file under `src/content/docs`.
-- To change the navigation sidebar, update `astro.config.mjs`.
-
-Note that all `.mdx` files requires a frontmatter.
+Run formatting before submitting a PR:
 
+```bash
+pnpm format
 ```
----
-title: Your page title.
----
 
-Your contents follows ...
+To check formatting without modifying files:
+
+```bash
+pnpm format:check
 ```