Thank you for your interest in improving nself documentation! Good documentation helps developers get started faster and use nself more effectively. This guide explains how to contribute to the docs, from fixing typos to writing new guides.
Great documentation is as important as great code. Whether you're fixing a typo or writing a comprehensive guide, your contribution helps thousands of developers.
# Clone the documentation repository
git clone https://github.com/acamarata/nself-web.git
cd nself-web/docs
# Install dependencies
npm install
# Start development server
npm run dev
# Open in browser
# http://localhost:3011docs/
├── src/
│ ├── app/ # Pages (Next.js App Router)
│ │ ├── page.tsx # Home page
│ │ ├── quick-start/
│ │ │ └── page.tsx # Quick start guide
│ │ ├── installation/
│ │ │ └── page.tsx # Installation guide
│ │ ├── configuration/
│ │ │ └── page.tsx # Configuration reference
│ │ └── [topic]/
│ │ └── page.tsx # Topic-specific pages
│ ├── components/ # Shared React components
│ │ ├── Navigation.tsx # Sidebar navigation
│ │ ├── Icon.tsx # Icon component
│ │ └── ...
│ └── lib/ # Utilities
├── public/ # Static assets
│ ├── images/
│ └── ...
├── package.json
└── next.config.jsEach documentation page follows a consistent structure:
'use client'
import { Icon } from '@/components/Icon'
import { Navigation } from '@/components/Navigation'
export default function MyTopicPage() {
return (
<div className="relative mx-auto flex w-full max-w-8xl flex-auto justify-center sm:px-2 lg:px-8 xl:px-12">
{/* Sidebar Navigation */}
<div className="hidden lg:relative lg:block lg:flex-none">
<div className="absolute inset-y-0 right-0 w-[50vw] bg-slate-50 dark:hidden" />
<div className="sticky top-[4.75rem] -ml-0.5 h-[calc(100vh-4.75rem)] w-64 overflow-y-auto py-16 pl-0.5 pr-8 xl:w-72 xl:pr-16">
<Navigation />
</div>
</div>
{/* Main Content */}
<div className="min-w-0 max-w-2xl flex-auto px-4 py-16 lg:max-w-none lg:pr-0 lg:pl-8 xl:px-16">
<div className="typography max-w-none">
{/* Page Title */}
<h1 className="inline bg-gradient-to-r from-indigo-200 via-sky-400 to-indigo-200 bg-clip-text font-display text-4xl tracking-tight text-transparent">
My Topic
</h1>
<hr className="my-8" />
{/* Version Badge */}
<div className="not-prose mb-6 flex gap-3">
<span className="inline-flex items-center rounded-md bg-sky-50 dark:bg-sky-400/10 px-2 py-1 text-xs font-medium text-sky-700 dark:text-sky-400">
v0.4.8
</span>
</div>
{/* Introduction */}
<p>
Brief introduction to what this page covers...
</p>
{/* Content sections */}
<h2>Section Title</h2>
<p>Content...</p>
<h3>Subsection</h3>
<pre className="language-bash">
<code>{`# Code example`}</code>
</pre>
{/* Next Steps */}
<h2>Next Steps</h2>
<ul>
<li><a href="/related-topic">Related Topic</a></li>
</ul>
</div>
</div>
</div>
)
}# Good Writing Examples
## Be Direct
Good: "Run 'nself start' to start all services."
Bad: "In order to start the services, you should run the start command."
## Use Active Voice
Good: "nself generates the configuration automatically."
Bad: "The configuration is generated automatically by nself."
## Include Context
Good: "The .env.secrets file stores sensitive credentials like database
passwords. This file should never be committed to git."
Bad: "The .env.secrets file stores credentials."
## Provide Examples
Good:
# Create a new project
nself init my-app
cd my-app
nself start
Bad:
Use the init command to create a project.{/* Good: Complete, working example */}
<pre className="language-bash">
<code>{`# Install nself
curl -fsSL nself.org/install.sh | bash
# Create a new project
nself init my-app
cd my-app
# Start services
nself start
# Check status
nself status`}</code>
</pre>
{/* Include language hint for syntax highlighting */}
<pre className="language-typescript"> {/* TypeScript */}
<pre className="language-sql"> {/* SQL */}
<pre className="language-json"> {/* JSON */}
<pre className="language-yaml"> {/* YAML */}{/* Info/Tip Box (Blue) */}
<div className="my-6 rounded-lg bg-blue-50 dark:bg-blue-900/20 p-4 border border-blue-200 dark:border-blue-800">
<div className="flex">
<Icon icon="lightbulb" color="blue" className="h-6 w-6 flex-shrink-0" />
<div className="ml-3">
<h3 className="text-sm font-medium text-blue-800 dark:text-blue-200 mt-0">
Pro Tip
</h3>
<div className="mt-2 text-sm text-blue-700 dark:text-blue-300">
<p>Helpful tip or additional information...</p>
</div>
</div>
</div>
</div>
{/* Warning Box (Yellow) */}
<div className="my-6 rounded-lg bg-yellow-50 dark:bg-yellow-900/20 p-4 border border-yellow-200 dark:border-yellow-800">
<div className="flex">
<Icon icon="warning" color="amber" className="h-6 w-6 flex-shrink-0" />
<div className="ml-3">
<h3 className="text-sm font-medium text-yellow-800 dark:text-yellow-200 mt-0">
Warning
</h3>
<div className="mt-2 text-sm text-yellow-700 dark:text-yellow-300">
<p>Important warning or caution...</p>
</div>
</div>
</div>
</div>
{/* Success/New Feature Box (Green) */}
<div className="my-6 rounded-lg bg-green-50 dark:bg-green-900/20 p-4 border border-green-200 dark:border-green-800">
<h3 className="text-lg font-semibold text-green-800 dark:text-green-400 mt-0 mb-2">
New in v0.4.8
</h3>
<p className="text-green-700 dark:text-green-300">
Description of new feature...
</p>
</div>
{/* Danger/Critical Box (Red) */}
<div className="my-6 rounded-lg bg-red-50 dark:bg-red-900/20 p-4 border border-red-200 dark:border-red-800">
<h3 className="text-sm font-medium text-red-800 dark:text-red-200 mt-0">
Critical
</h3>
<p className="text-red-700 dark:text-red-300">
Critical information about potential data loss or security...
</p>
</div># Create directory for your topic
mkdir -p src/app/my-new-topic
# Create the page file
touch src/app/my-new-topic/page.tsxUse the page template shown above as a starting point. Include:
// src/components/Navigation.tsx
// Add your page to the appropriate section
const navigation = [
{
title: 'Getting Started',
links: [
{ title: 'Quick Start', href: '/quick-start' },
{ title: 'Installation', href: '/installation' },
{ title: 'My New Topic', href: '/my-new-topic' }, // Add here
],
},
// ...
]# Start dev server
npm run dev
# Check your page at:
# http://localhost:3011/my-new-topic
# Verify:
# - Page loads without errors
# - Navigation works
# - Code examples render correctly
# - Dark mode looks good
# - Mobile responsive# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/nself-web.git
cd nself-web/docs
# Create a branch
git checkout -b fix/typo-in-installation
# Make your changes
# ...
# Commit and push
git add .
git commit -m "docs: fix typo in installation guide"
git push origin fix/typo-in-installation
# Create pull request on GitHub## Description
Brief description of documentation changes
## Type of Change
- [ ] Typo/grammar fix
- [ ] Content improvement
- [ ] New documentation page
- [ ] Restructuring existing content
## Checklist
- [ ] I've tested the changes locally
- [ ] Code examples are complete and working
- [ ] Navigation is updated (if adding new pages)
- [ ] Dark mode renders correctly
- [ ] Mobile responsive
- [ ] Links work correctly
## Screenshots (if applicable)
Add screenshots for visual changes{/* Always include version badge for version-specific content */}
<div className="not-prose mb-6 flex gap-3">
<span className="inline-flex items-center rounded-md bg-sky-50 dark:bg-sky-400/10 px-2 py-1 text-xs font-medium text-sky-700 dark:text-sky-400 ring-1 ring-inset ring-sky-700/10 dark:ring-sky-400/30">
v0.4.8
</span>
<span className="inline-flex items-center text-sm text-slate-500 dark:text-slate-400">
Updated for nself v0.4.8
</span>
</div>
{/* For new features, use the green highlight box */}
<div className="rounded-lg bg-gradient-to-r from-green-50 to-emerald-50 border border-green-200 p-4 mb-6 dark:bg-gradient-to-r dark:from-green-900/20 dark:to-emerald-900/20 dark:border-green-800">
<h3 className="text-lg font-semibold mb-2 text-green-800 dark:text-green-400">
New in v0.4.8
</h3>
<ul className="space-y-1 text-green-700 dark:text-green-300">
<li>* <strong>Feature name:</strong> Description</li>
</ul>
</div>{/* Internal links - use relative paths */}
<a href="/configuration">Configuration Guide</a>
<a href="/cli-env">CLI Environment Commands</a>
{/* External links - use full URLs */}
<a href="https://hasura.io/docs">Hasura Documentation</a>
{/* Next Steps section at end of each page */}
<h2>Next Steps</h2>
<ul>
<li><a href="/related-topic">Related Topic</a> - Brief description</li>
<li><a href="/another-topic">Another Topic</a> - Brief description</li>
</ul><table>
<thead>
<tr>
<th>Column 1</th>
<th>Column 2</th>
<th>Column 3</th>
</tr>
</thead>
<tbody>
<tr>
<td>Data 1</td>
<td>Data 2</td>
<td>Data 3</td>
</tr>
</tbody>
</table>npm run build completes without errors# Start development server
npm run dev
# Build for production
npm run build
# Check for broken links (if link checker is available)
npm run check-links
# Lint TypeScript
npm run lint{/* For CLI command documentation */}
<h2>Command: nself example</h2>
<pre className="language-bash">
<code>{`nself example [options] <argument>`}</code>
</pre>
<h3>Arguments</h3>
<table>
<thead>
<tr>
<th>Argument</th>
<th>Description</th>
<th>Required</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>argument</code></td>
<td>Description of argument</td>
<td>Yes</td>
</tr>
</tbody>
</table>
<h3>Options</h3>
<table>
<thead>
<tr>
<th>Option</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>--flag</code></td>
<td>Description of flag</td>
<td>false</td>
</tr>
</tbody>
</table>
<h3>Examples</h3>
<pre className="language-bash">
<code>{`# Basic usage
nself example arg
# With options
nself example arg --flag`}</code>
</pre>Documentation contributors are recognized in several ways:
Every documentation improvement helps developers succeed with nself. Your contributions make a real difference - thank you for helping make nself better!
Ready to contribute? Pick an issue labeled "documentation" or "good first issue" and start improving the docs today!