Loading...

Skip to main content

Aliz Dev Hub Is Live 🚀

· 4 min read
Gergely Sipos
Gergely Sipos
Frontend Architect at Aliz

We've been talking about it for a while, and now it's real: the Aliz Dev Hub is live. It's our collective engineering handbook — a single place where we capture what actually works at Aliz, from GCP patterns to frontend conventions to infrastructure decisions.

It's not a wiki. It's not a Confluence space. It's a Docusaurus site backed by Git, reviewed through pull requests, and deployed like any other piece of software we ship.

What This Is​

The Dev Hub is an internal knowledge base structured around the engineering domains we work in every day:

  • Infrastructure — networking, compute, IaC with Terraform
  • Data — BigQuery, Dataflow, pipeline design
  • Application Development — backend services, APIs, system design
  • Web — TypeScript, frontend frameworks, browser platform

Each section has its structure in place. The skeleton is there. What's missing is the flesh — and that's where every engineering track comes in.

Why Not a Wiki?​

We've all seen what happens to wikis. Someone writes a page in 2022, nobody touches it again, and by 2024 it's actively misleading. The problem isn't that people are lazy — it's that wikis have no quality gate. There's no review, no ownership signal, no natural moment to check if something is still true.

The Dev Hub lives in a Git repository. Contributing means opening a pull request. That gives us:

  • Code review for docs — someone else reads it before it merges
  • History and blame — you can see who wrote what and when
  • Freshness signals — stale content shows up in commit history (or lack thereof)
  • The same workflow we already use — no new tool, no new login, no context switch

This doesn't magically solve the staleness problem, but it makes the cost of updating low and the visibility of neglect high.

What Makes This Different from Official Docs​

The Dev Hub is not a mirror of Google Cloud documentation or MDN Web Docs. Those already exist and are excellent. What they don't tell you is:

  • Which of the three possible approaches we actually use at Aliz and why
  • What configuration patterns have bitten us in production
  • How we structure projects, name things, and make trade-offs
  • What the recommended path is when you're starting a new service tomorrow

This is opinionated guidance. It captures decisions, not just options.

tip

Think of it this way: official docs tell you what a tool can do. The Dev Hub tells you what we actually do with it — and what we stopped doing after it broke.

How to Contribute​

The repository is aliz-dev-hub on GitHub. The docs live in dev-hub-website/docs/ as Markdown files.

Contributing is straightforward:

  1. Clone the repo
  2. Find the right section (or create a new page)
  3. Write your content in Markdown
  4. Open a pull request

That's it. No special tooling, no CMS, no permissions to request.

note

You don't need to write a masterpiece. A short page explaining one decision, one pattern, or one "don't do this" is valuable. The bar is usefulness, not length.

If you're unsure where something belongs or want to propose a new section, open an issue first — or just ask in the PR description.

It's Early Days​

Let's be honest: the hub is mostly empty right now. The structure exists, but the content is minimal. That's intentional. We didn't want to pre-fill it with placeholder text that nobody owns. Instead, this is a starting point — a scaffold that each engineering track can fill with the knowledge they find genuinely valuable.

The value of this thing scales with contributions. One person writing docs is a blog. Thirty engineers capturing their hard-won knowledge is a competitive advantage.

Further Reading​