John

Senior Cloud Engineer & Technical Lead

Style Guide

This guide defines the writing style, formatting standards, and content guidelines for the johnoct.github.io blog.

Writing Style

Tone and Voice

Personal and Authentic

Conversational yet Technical

Action-Oriented

Content Structure

Standard Article Format

  1. Personal Hook (1-2 paragraphs)
    • Start with a real situation you encountered
    • Describe the context and why it mattered
    • Set up the problem or challenge
  2. Problem Definition (1-2 paragraphs)
    • Clearly explain the technical challenge
    • Provide enough context for understanding
    • Mention what you tried initially
  3. Solution Presentation (2-4 sections)
    • Break down your approach into logical steps
    • Include code examples and configurations
    • Explain the reasoning behind decisions
    • Show the implementation process
  4. Key Learnings (bullet points)
    • 3-5 concise takeaways
    • Focus on what you’d do differently
    • Highlight important gotchas or insights
    • Include broader lessons applicable to similar situations

Example Structure

I recently ran into an interesting challenge while optimizing costs for a multi-account AWS setup. We were seeing unexpected charges that didn't align with our resource usage, and traditional cost analysis tools weren't giving us the granular insights we needed.

## The Problem

Our monthly AWS bill had grown by 40% over three months, but our application usage remained relatively stable. The Cost Explorer showed general trends but couldn't pinpoint exactly where the extra spending was coming from...

## The Solution

After digging deeper, I discovered the issue was related to data transfer costs between regions. Here's how I solved it:

### Step 1: Identify Cross-Region Traffic

First, I enabled VPC Flow Logs to track network traffic patterns:

```bash
aws ec2 create-flow-logs \
    --resource-type VPC \
    --resource-ids vpc-12345678 \
    --traffic-type ALL \
    --log-destination-type cloud-watch-logs \
    --log-group-name VPCFlowLogs

Key Learnings

Language Guidelines

Preferred Patterns

Use:

Avoid:

Technical Specificity

Good Examples:

I configured the ECS service with a target tracking scaling policy:

```json
{
  "TargetValue": 70.0,
  "ScaleOutCooldown": 300,
  "MetricType": "ECSServiceAverageCPUUtilization"
}

This kept CPU utilization between 60-80% during peak hours.


**Poor Example:**
```markdown
I set up auto-scaling for better performance. It's important to configure the right metrics and thresholds for your use case.

Formatting Standards

Headers and Structure

Hierarchy

Consistent Section Names

Code and Technical Content

Code Blocks

Always specify language for syntax highlighting:

# Shell commands
aws s3 sync ./build s3://my-bucket --delete

# YAML configurations
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::my-bucket/*"
    }
  ]
}

Inline Code

Use backticks for commands, filenames, and technical terms:

Command Context

Provide context for commands:

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Link Text

Use descriptive link text that indicates the destination:

Good:

Poor:

External References

Lists and Bullet Points

Key Learnings Format

Use parallel structure and action-oriented language:

Good:

Poor:

Technical Lists

Use consistent formatting for step-by-step instructions:

  1. Configure the load balancer 
    aws elbv2 create-load-balancer --name my-lb --subnets subnet-12345
  2. Create target group 
    aws elbv2 create-target-group --name my-targets --port 80 --protocol HTTP
  3. Register targets 
    aws elbv2 register-targets --target-group-arn arn:aws:elasticloadbalancing:...

Content Guidelines

Technical Accuracy

Verification Requirements

Error Handling

Address common issues and edge cases:

## Troubleshooting

If you encounter permission errors:

```bash
# Check current IAM permissions
aws sts get-caller-identity

# Verify required policies are attached
aws iam list-attached-user-policies --user-name your-username

Common issues:

Scope and Focus

Article Length

Topic Depth

SEO and Discoverability

Title Guidelines

Good Titles:

Poor Titles:

Tag Strategy

Use 3-6 relevant tags per post:

GitHub Stars Content

Daily Posts Format

Automated posts should maintain consistency:

## 1. [Repository Name](https://github.com/user/repo)

**Author:** username | **Language:** Go | **Stars:** ⭐ 1,234

_Repository description from GitHub API._

**Topics:** topic1, topic2, topic3

---

Weekly Roundups Enhancement

Add personal commentary to curated collections:

## 1. [Repository Name](https://github.com/user/repo)

**Author:** username | **Language:** Go | **Stars:** ⭐ 1,234

_Repository description from GitHub API._

**Why it caught my attention:** This tool solves a specific problem I've encountered with Kubernetes networking. The approach to service mesh integration looks particularly promising for our use case.

**Topics:** topic1, topic2, topic3

---

Quality Checklist

Before Publishing

Content Review

Technical Review

Formatting Review

Metadata Review

Post-Publication

Performance Check

Content Validation

Remember: The goal is to share genuine technical insights that help other practitioners solve similar problems. Focus on practical value over completeness, and personal experience over generic advice.