The Problem

This repository addresses a common content-management pain point: keeping a hand-maintained index of technical articles synchronized with a structured data source. Without automation, adding a new article means editing both the raw data and the generated README table, which invites drift and formatting inconsistencies.

What This Does

The repo is a small, single-purpose tool that maintains a categorized index of technical writing (system design, backend engineering, distributed systems) published as Twitter/X threads. The content lives in articles.json, and the human-readable README.md table is generated from it.

The core logic is in generate_readme.py. It reads the JSON, groups articles by category, and writes the formatted Markdown tables you see in the README. There are no other moving parts: no tests, no CI, no dependencies beyond the Python standard library.

How It Is Wired

The repository has a single entry point: generate_readme.py. It loads articles.json, iterates over the categories and their articles, and writes the output to README.md. The import graph confirms this is a leaf module: it imports nothing internal (0 import edges, 1 module total), so there is no call chain to trace beyond the script itself.

  • generate_readme.py — the only code file; owns the entire generation logic.
  • articles.json — the data source; all article metadata (title, URL, description, date, category).
  • README.md — the generated output; should not be edited by hand.
  • LICENSE — standard MIT license.

The blast radius is tiny. A change to the script affects only the README's formatting. A change to the JSON affects the README's content. There are no shared modules, no circular dependencies, and no external services touched. The script is idempotent: running it twice produces the same output.

The one design choice worth noting: the README is generated, but there is no CI gate to enforce that it stays in sync with articles.json. A contributor could edit the README directly, or forget to regenerate it after a JSON change, and nothing would catch it.

How To Use It

Setup: No dependencies beyond Python 3. Clone the repo and run the script.

git clone https://github.com/moses-y/Technical-Engineering-Articles
cd Technical-Engineering-Articles
python generate_readme.py

Configuration: None. There are no environment variables, config files, or API keys. The script takes no arguments.

Running it: python generate_readme.py regenerates README.md from articles.json. That is the entire interface.

Real-World Use

This pattern fits any small content-index site where articles are stored as structured data and rendered to a static page. For example, a personal blog could use the same approach: keep posts in a JSON file, run a generator script in a pre-commit hook or CI job, and commit the rendered HTML or Markdown. The key is that the generator must be run as part of the publishing workflow, or the index will silently go stale.

Code Health & Issues

Static analysis (from this pipeline, not hand-inspection) reports: 1 internal module, 0 import edges, no circular dependencies. generate_readme.py has a cyclomatic instability of 0 (nothing imports it, it imports nothing).

  • Med - No tests - there are no test files; the generation logic is untested. A malformed JSON entry or an unexpected category would fail at runtime, not at test time. - repository-wide
  • Med - No CI/CD - no pipeline enforces that README.md matches articles.json. A stale README would go unnoticed. - .github/ or CI config absent

The repository is otherwise clean: MIT license present, no committed secrets, no lockfile (not needed for a stdlib-only script).

The Bottom Line

This is a minimal, working tool that does one thing well. It has no test coverage and no automation to keep the generated output honest, but for a single-author content index, the simplicity is a feature. Anyone who wants to maintain a categorized article list with a generated README can fork this and get value immediately; anyone expecting a full publishing pipeline should look elsewhere.