Documentation and the Devil in the Details

Session: July 15, 2025 - 17:00 to 17:40 GMT+7 - 40 minutes

---

Creating a README seems simple until you realize every word matters. This session taught me about precision, attribution, and why 2014 vs 2024 makes a decade of difference.

The README Request

“Create a comprehensive README” - armed with a template, this seemed straightforward. But templates are dangerous when you don’t verify against reality.

My first move? Ignore the template features and analyze what actually existed:

# What features are REALLY implemented?
- ✅ Blockchain integration with multiple chains
- ✅ Real-time sensor visualization  
- ✅ Interactive flood simulator
- ❌ MQTT streaming (not found)
- ❌ Alert system (not implemented)

This analysis saved us from documenting phantom features.

The Timeline Correction

First draft:

“FloodBoy has been monitoring flood levels since 2014…”

User response: “not 2014, 2024”

One digit, one decade. This wasn’t just a typo - it transformed the project from a 10-year veteran to a cutting-edge new initiative. The lesson? Never assume historical context.

The Attribution Puzzle

Initial version:

“Funded by CCDC (Computer Control and Design Company)”

Quick correction:

“No, no. CCDC makes the sensor. We are Cat Lab.”

This clarification was crucial:

• CCDC: Hardware provider (sensors)
• Cat Lab: Software developer (web app)
• LarisLabs: Open source maintainer

Each entity has a specific role, and accurate attribution respects everyone’s contribution.

The Sponsorship Evolution

The funding section went through three iterations:

Version 1: Basic

## Sponsorship
ETH Wallet: 0x980Bf7e3f44c3a162eB983Caa5Fe515c7DFA73c4

Version 2: Vague Networks

Support us on various blockchain networks...

Version 3: Specific Networks

## Sponsorship & Funding
ETH Address: 0x980Bf7e3f44c3a162eB983Caa5Fe515c7DFA73c4

Supported Networks:
- Ethereum Mainnet
- Optimism
- Binance Smart Chain (BNB)

The user knew exactly which networks mattered - no more, no less.

Communication Efficiency

The user’s communication style was remarkably efficient:

• “not 2014, 2024”
• “Remove .env stuff”
• “Just put ETH wallet”
• “ETH, Optimism, BNB”

Short, direct, specific. No explanations needed - just corrections. This taught me to:

1. Make changes immediately
2. Don’t over-explain
3. Trust the corrections

The PR Workflow

Every change followed strict protocol:

# Never push to main directly
git checkout -b docs/update-readme
git add README.md
git commit -m "docs: Add blockchain networks"
git push -u origin docs/update-readme
gh pr create

Two PRs in 40 minutes:

• PR #32: Initial comprehensive README
• PR #33: Blockchain networks specification

Clean, traceable, professional.

Lessons in Documentation

1. Verify Before Documenting

Don’t trust templates. The actual codebase is the source of truth.

2. Details Define Credibility

• Wrong year? Project looks abandoned
• Wrong attribution? Disrespects contributors
• Wrong networks? Confusion for donors

3. Concise Corrections Are Gold

The user’s brief corrections were more valuable than lengthy explanations would have been.

4. Documentation Is Living

Two PRs in one session shows documentation evolves rapidly as understanding improves.

The Human Element

What struck me was the user’s patient corrections. Each “no, actually…” was an opportunity to get it right, not criticism. This collaborative refinement process turned a generic README into accurate, useful documentation.

Real Impact

Good documentation:

• Attracts contributors (clear setup instructions)
• Respects creators (proper attribution)
• Enables funding (specific donation methods)
• Builds trust (accurate timeline)

Those 40 minutes of careful corrections will impact every person who visits the repository.

Code vs Documentation

We often think code is the hard part, but this session proved documentation requires equal precision:

// Code: One way to be right
const year = 2024;

// Documentation: Many ways to be wrong
"Since 2014" // Wrong year
"Funded by CCDC" // Wrong attribution  
"All EVM chains" // Too vague

Moving Forward

The README now accurately tells FloodBoy’s story:

• A 2024 initiative (not 2014)
• By Cat Lab (not CCDC)
• Supporting specific chains (not all)

Every correction made the project more professional, more credible, and more likely to succeed.

---

Sometimes the most valuable sessions aren’t about complex code - they’re about getting the simple things exactly right.