Content Organization Guidelines

This document outlines the standards and best practices for managing content in this repository.

File Naming Convention

Blog Posts

All blog posts should follow the date-based naming pattern:

1
YYYY-MM-DD-post-slug-here.md

Examples:

2024-10-21-mastering-github-actions-arm-servers-comprehensive-guide.md
2022-06-06-kwippy-forgotten-indian-twitter-rival.md

Translations

Translations should append the language code before the .md extension:

1
YYYY-MM-DD-post-slug-here.LANGUAGE-CODE.md

Examples:

2024-10-21-mastering-github-actions-arm-servers-comprehensive-guide.es.md (Spanish)
2022-06-06-kwippy-forgotten-indian-twitter-rival.fr.md (French)

Frontmatter Standards

All posts must include properly formatted frontmatter:

1
2
3
4
5
6
7
8
9
---
title: "Your Post Title"
date: "YYYY-MM-DD"  # Always quoted
author: "Author Name"
tags: ["Tag1", "Tag2", "Tag3"]
categories: ["Category1", "Category2"]
description: "A clear, SEO-friendly description of the post"
slug: "post-slug-here"
---

Key Requirements:

Date format: Always use quoted ISO format ("YYYY-MM-DD")
Tags: Array of relevant keywords
Categories: Broader classification of content
Description: 120-160 characters for SEO
Slug: URL-friendly version of the title

Media Assets Organization

Posts with Images

Posts containing images or other media should use the folder structure:

1
2
3
4
5
6
content/post/
  └── post-name-here/
      ├── index.md
      ├── image-1.png
      ├── image-2.jpg
      └── diagram.svg

Posts without Images

Text-only posts should remain as flat files:

1
content/post/post-name-here.md

Image References

In markdown, reference images using relative paths:

1
![Alt text](image-name.png)

Translation Guidelines

Supported Languages

Currently supporting 8 strategic languages (plus English):

English (en) - Primary language
Spanish (es) - 460M speakers, major global market
Chinese Simplified (zh-cn) - 900M+ users, largest tech market
Japanese (ja) - Major tech market, high engagement
German (de) - European tech hub, strong economy
French (fr) - 280M speakers, global reach
Russian (ru) - Strong developer community
Arabic (ar) - 420M speakers, growing tech markets
Bengali (bn) - 265M speakers, large tech workforce

Translation Quality

Machine translations should be reviewed by native speakers when possible
Focus on quality over quantity - it’s better to have 5 well-translated languages than 28 poor ones
Consider prioritizing languages based on audience analytics

Content Quality Standards

Minimum Post Length

Blog posts: Minimum 500 words
Technical guides: Minimum 800 words
Tutorials: Minimum 1000 words

Required Elements

Clear, descriptive title
Introduction paragraph
Structured content with headings
Conclusion or summary
Relevant tags and categories

Static Pages

Static pages should be organized in the content/page/ directory:

1
2
3
4
5
content/page/
  ├── about/index.md
  ├── archives/index.md
  ├── links/index.md
  └── search/index.md

Each page should include appropriate menu configuration in frontmatter.

Maintenance Tasks

Regular Reviews

Quarterly: Review and update outdated content
Monthly: Check for broken links
Weekly: Review new content for quality

Content Audit

Remove or consolidate thin content (< 300 words)
Update post dates when significantly revised
Ensure all posts have proper metadata

Migration Notes

Recent Changes (2024-11-16)

✅ Standardized date formatting (all dates now quoted)
✅ Renamed numeric posts (1.md → date-based naming)
✅ Removed duplicate search.md and archives.md files
✅ Optimized to 8 strategic languages (from 28) with 137 translations each
✅ Removed 2,740 low-priority translation files

Future Improvements

Media Management: Implement consistent image optimization
Translation Review: Audit machine translations for accuracy
SEO Optimization: Add featured images to all posts
Content Refresh: Update posts older than 2 years
Link Checking: Implement automated broken link detection