This guide ensures consistency across all blog posts and technical documentation.
Loading actions...
This guide ensures consistency across all blog posts and technical documentation.
Never assume readers know what acronyms mean. Always explain technical terms and acronyms on first use, even if they seem common in our field.
On first use, write the full term followed by the acronym in parentheses:
✅ GOOD: Progressive Web App (PWA)
✅ GOOD: Test-Driven Development (TDD)
✅ GOOD: Server-Side Rendering (SSR)
❌ BAD: PWA support included
❌ BAD: Use TDD approach
❌ BAD: Avoid SSR hydration issues
After first use, use the acronym freely:
✅ GOOD:
Progressive Web App (PWA) support with offline capabilities via Workbox.
The PWA includes service worker registration and manifest configuration.
❌ BAD:
PWA support with offline capabilities. The PWA includes...
Always explain these on first use:
SpokeToWork-specific terms that need explanation:
- **[Tailwind CSS](https://tailwindcss.com/) (Cascading Style Sheets) v4**
- **WCAG (Web Content Accessibility Guidelines) 2.1 AA compliance ready**
- **E2E (End-to-End) testing (40+ tests)**
- **[IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) for local data storage**
# First mention
Progressive Web App (PWA) support with offline capabilities.
# Subsequent mentions
The PWA includes service worker registration...
Configure your PWA manifest...
✅ GOOD: "Server-Side Rendering (SSR) generates HTML on the server before sending to the client."
❌ BAD: "Use SSR for better performance."
✅ GOOD: "The component renders the countdown timer."
❌ BAD: "The countdown timer is rendered by the component."
Goal: Make content more scannable and engaging while maintaining professionalism.
Technical Domains (use in headers):
Status Markers (use in callouts):
Action Indicators:
DO:
## 🔒 Authentication Flows
⚠️ **Important**: Never expose API keys in client-side code.
✅ **Best Practice**: Use environment variables for secrets.
### 💳 Payment Integration
DON'T:
## 🔒🛡️💳 Authentication and Payment 🚀✨ (too many emojis)
🎉 This section is about payments! 💰💵💴 (unprofessional tone)
## 🗄️ Why We Chose Supabase
⚠️ **Security Gotcha**: Row-Level Security policies must be tested with both authenticated and anonymous users.
### 🔧 Configuration Steps
1. 📦 Install dependencies: `npm install @supabase/supabase-js`
2. 🔑 Add environment variables to `.env.local`
3. ✅ Test connection with `supabase status`
// 🚀 Performance: Memoize expensive calculations
const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);
// 🐛 Fix: Prevents memory leak on unmount
return () => clearInterval(timer);
// ⚠️ Warning: This breaks SSR - only run on client
if (typeof window !== 'undefined') {
localStorage.setItem('key', value);
}
✅ GOOD:
**Timer Logic**: Calculate milliseconds to Jan 1st midnight (local timezone), convert to days/hours/minutes/seconds with modulo math
```tsx
const calculateTimeLeft = () => {
const targetDate = new Date(new Date().getFullYear() + 1, 0, 1);
// ...
};
```
❌ BAD:
const calculateTimeLeft = () => {
// code without explanation
};
### Inline Comments for Key Concepts
When code demonstrates an important concept, add inline comments:
```tsx
✅ GOOD:
const [mounted, setMounted] = useState(false); // Avoid SSR hydration mismatch
✅ GOOD:
return () => clearInterval(timer); // Cleanup prevents memory leaks
✅ GOOD: "## 5. The Code (TDD: Tests First, Then Implementation)"
✅ GOOD: "## Why Countdown Timers Work"
❌ BAD: "## Code"
❌ BAD: "## Implementation"
✅ GOOD: **[Next.js](https://nextjs.org/) 15.5.2** with App Router
✅ GOOD: **[Vitest](https://vitest.dev/)** for unit tests
❌ BAD: Next.js 15.5.2 with App Router
Before publishing, verify:
Target reading times based on content type:
Don't sacrifice clarity for brevity. Better to be thorough than terse.
Last updated: 2025-10-07