Why Developer Portals Fail: Rethinking Search, Docs, and UI/CLI Experience

Background: The 2D (to‑Developer) Trend

In recent years, the rise of productized technology has pushed many companies—cloud vendors and open‑source firms alike—to expose their software directly to developers, creating a booming "to‑developer" market. However, most of these portals prioritize superficial UI flows (e.g., three‑click project creation, drag‑and‑drop pipelines, simple dropdown search) without considering the real needs of experienced developers.

Search Box Experience Design

Typical vendor search boxes offer limited functionality: you click a button, select criteria, and get results. The author points out the lack of expressive power, such as the inability to use custom queries or shortcuts. For example, AWS provides a shortcut Option+S to open its search, but the underlying experience remains basic.

The author criticizes such designs for lacking features like advanced filtering, syntax‑based queries, and keyboard‑driven interactions that power users expect.

Code‑Based Search Box (ArchGuard Insight PoC)

In the open‑source project ArchGuard , a proof‑of‑concept called Insight implements an expression‑driven search box using the Monaco Editor, inspired by Sourcegraph. The search syntax looks like: field:dep_name==%dubbo% field:dep_version>1.12.3 This approach treats the search input as code, enabling syntax highlighting, autocomplete, context linking, and validation.

Implementing such a feature requires work on:

Custom language definition, syntax parsing, highlighting, and auto‑completion in Monaco.

Automatic context association.

Expression design and validation.

Extensibility for future fields.

These tasks are non‑trivial but yield a far more powerful developer experience.

Documentation Experience: The “Dog Shakes Head” Problem

The author laments that many docs are written for newcomers or as after‑thoughts, resulting in:

Out‑of‑date API references.

Frequent, manual API changes.

Inconsistent terminology.

Duplicated content blocks.

Code snippets that do not run.

When documentation is unreliable, developers either skip it or waste time hunting broken links, leading to the metaphor of a dog shaking its head at nonsensical URLs.

Improving Documentation as an Engineering Discipline

Key recommendations include treating documentation as code, using meaningful URL naming, linking code errors to docs, and automating sync between code and docs.

UI vs CLI: Who Should Care?

The article questions whether a CLI‑first approach would force better UI design. It highlights the need for:

CLI documentation experience.

Automatic migration tools when services update.

Robust CLI update mechanisms.

Neglecting these aspects perpetuates poor developer experience.

Conclusion

Developer experience should be a first‑class concern. Treating portals, search, and documentation as engineering artifacts—complete with expressive APIs, versioned docs, and meaningful UI/CLI design—can prevent the “dog‑shaking‑head” frustration and deliver real value to developers.