TCDEV Blog

When Your Users Code With AI, What Does DevRel Actually Teach?

2026-05-03T00:00:00Z

A friend of mine runs DevRel at a mid-size API company. We were on a call last week, and he said something that stuck: "I have no idea what content to produce anymore."

His team built their reputation on tutorials. Videos, written walkthroughs, the polished "How to set up auth in 10 minutes" stuff. Easily a million views and reads across their channels. And then, sometime in the last 18 months, the numbers stopped growing. Not because people lost interest in the product. Because nobody needs the tutorials anymore.

They sit in Cursor or Copilot, type "add auth using SDK X", and get working code back. The tutorial gets read by the model, not by them.

So what does DevRel actually teach now?

The thing AI does well is also the thing tutorials do

Step-by-step instructional content is exactly the format LLMs were trained on. Millions of Stack Overflow answers, README files, dev.to posts, official docs. When you ask Claude how to do something concrete and well-documented, it composes those patterns better than most humans can.

The numbers say this is not a fringe behaviour anymore. GitHub's 2024 Octoverse report showed AI tools are now part of mainstream developer workflow across every major language ecosystem. Stack Overflow's 2024 Developer Survey found 76% of developers using or planning to use AI tools, with 72% of professional developers favourable or very favourable toward them. Stack Overflow itself reported a meaningful drop in question volume over the same period, which the moderators correlate with people asking AI first.

Reading is still happening. The reader changed.

If you produce content that competes with what an LLM can already generate from your own docs, you are competing with the model on its strongest ground. That is not a fight I would pick.

What AI cannot do (yet)

It cannot tell me why.

Why does this SDK use long-polling instead of websockets. Why is rate-limiting bucketed per token rather than per IP. Why did your team kill the v1 schema even though plenty of customers still relied on it. Why is the recommended pattern actually the recommended pattern, and what happens when you ignore it.

These are all things models can guess at. They do, sometimes confidently. But guesses are not the same as the answer from someone who was in the room when the decision was made.

When someone integrating my work has Copilot do the wiring, the value of human-produced content shifts upward in the stack. They do not need my "getting started." They need:

The reasoning behind the API design
The failure modes the SDK does not surface clearly
The patterns that look fine but break at scale
Honest comparisons with the alternative tools they are also evaluating
Direct access to a human when they hit something weird

That last one matters more than people credit. A Discord ping to an actual maintainer is something an LLM cannot reproduce, and the bar for what counts as "good DevRel" in 2026 is increasingly about whether that ping gets answered.

Mental models, not muscle memory

Honestly, I do this myself. When I am picking up a new framework, I no longer want a 40-minute video walking me through npm install to "hello world." I want a 10-minute talk where the creator explains the three or four ideas that make the framework feel different from the others.

That is teachable content AI does not replace. It is opinionated, contextual, and it is the layer above the API surface. The mental model. The taste. The specific failure mode the maintainer fixed last year because someone hit it in production.

A good example I keep coming back to is the way the HTMX team writes essays alongside their docs. The docs explain syntax. The essays explain worldview. The essays are what convert people, and they are also exactly the thing an LLM has the hardest time replicating from a corpus, because they do not exist in the corpus until the maintainer writes them.

This is part of why I think DevRel is more important now, not less. The job just stopped being "make people aware of feature X." It is now: build the explanation no model could produce on its own.

What this means for the day-to-day

A few things are worth saying out loud, because the implications for how you spend your week are real.

Stop measuring tutorial views as a primary KPI. They are going to keep dropping, and the drop is not your fault. Measure depth signals instead. Time-on-page for design rationale posts. GitHub Discussions activity. Office-hours attendance. Things that imply the human stayed for the part the AI cannot give them.

Move some content into the AI's diet on purpose. Make sure your docs are clean, structured, and machine-readable, because the AI is now your most prolific reader. If your docs are messy, every Copilot autocomplete in your ecosystem gets quietly worse. There is a real first-mover advantage here for teams who treat their docs as input data, not just output.

Be more present, not more polished. The trend I keep seeing is that the DevRel folks who are doing well right now are not the ones with the slickest content. They are the ones who answer Discord messages within an hour, who jump into community calls, who write the messy "here is the post-mortem of what we got wrong" essays.

The job changed from explaining how to build with your product to explaining why your product was built that way, and being available when someone needs the human in the loop.

If your DevRel strategy still assumes humans will sit through your tutorials, it is quietly aging out. The good news is the new job is more interesting. The bad news is it is harder to fake, because models are getting really good at the part that used to pad the calendar.

I am still figuring out what mine should look like. Honestly, I think most of us are.

AI Answers and the Trust Problem in Developer Communities

2026-04-30T00:00:00Z

A few weeks ago I was lurking in a Discord for a tool I use occasionally. Someone asked a fairly specific question about a config edge case. Two minutes later, a confident-sounding answer appeared from a regular member. The answer had the right shape. Right code style. Plausible API references. Half of it was wrong.

Nobody caught it for almost a day. The person who asked actually thanked the responder, went off, presumably wasted a couple of hours, and came back annoyed.

I do not know for sure that the answer was AI-generated. I am pretty sure though. And the reason I am pretty sure is that this is the new failure mode in developer communities, and once you start looking for it, it is everywhere.

The Stack Overflow story is the obvious one

In December 2022, Stack Overflow issued a temporary ban on ChatGPT-generated answers. The reasoning was direct: the answers had a high error rate, but they looked correct, which made them harder to moderate than just bad answers from humans. Plausible-but-wrong is more dangerous than obviously-wrong.

That ban became permanent policy and then, in May 2024, Stack Overflow announced a partnership with OpenAI to feed Stack Overflow content into ChatGPT. So the platform that banned AI-generated answers started licensing its human-generated answers to train the AI generating those answers. A lot of users were not thrilled. Some deleted their highest-voted answers in protest, and a number got suspended for it.

Meanwhile the actual question volume on Stack Overflow has continued to decline, with various analyses pointing at the obvious cause. People ask the AI first.

That sequence of events is messy in the telling, but the underlying tension is simple. Communities exist because humans contribute knowledge to other humans. The moment the contribution might not be human, and might not even be correct, the trust contract breaks. And once trust breaks in a community, the contributors leave first. Then the answer quality drops further. Then the readers leave too. The doom loop is well documented.

This is not a Stack Overflow problem, it is everyone's problem

Run a Discord. Run a Discourse. Run a subreddit. Run a Slack workspace for your open source project. The same dynamic is showing up everywhere, just less visibly.

I have seen it in:

A Discord where a couple of "helpful" members were clearly piping every question through ChatGPT and pasting the response, complete with hallucinated method names
A Discourse forum where a moderator noticed answers in a niche subforum suddenly getting more polished but less correct
A subreddit where the moderators had to add a rule about AI-generated submissions because low-effort posts were drowning out the genuine ones

The pattern is always the same. AI lowers the cost of producing a plausible answer to roughly zero. Plausibility is the thing that historically gated who got upvoted, replied to, or believed. And now the gate does not work.

Common Room's community research and the Orbit model's writing on community health both point at the same underlying signal: communities live or die on the trust relationships between members. AI-generated content does not just add noise. It poisons the signal that lets a community function in the first place.

The honest unresolved tension

Here is the part nobody has a clean answer to, and the reason I think this is the conversation worth having:

Faster answers are good. Reliable answers are good. Right now you can have one or the other, not both.

If your Discord allows AI-generated responses, your average response time goes down and your accuracy gets noisier. If you ban them, you slow the community down and probably can't enforce the ban anyway, because plausibility is exactly what makes detection hard.

There are some directions that look promising, but none of them are settled.

Disclosure norms. Some communities have adopted a culture of marking AI-assisted answers explicitly. "Claude says this, I have not verified it." This works in small, healthy communities. It scales poorly because the bad actors are exactly the ones who will not disclose.

Reputation gating. Make the cost of contributing high enough that low-effort AI dumps are filtered out by the contribution friction itself. This is basically what Stack Overflow's reputation system was designed to do, before AI shifted the cost equation.

Human-only spaces. A few projects I have seen are explicitly carving out invitation-only or paid spaces for "verified human" conversation. There is a real argument for this, and it is also depressing as hell, because what we are saying is that open developer community is becoming a thing you have to pay to access.

AI as triage, not as answer. The most workable pattern I have seen is using AI to summarize, route, and tag, while keeping the actual answer human. The model is doing the boring work, the human is providing the credibility. This is roughly what the better-run community teams I know are doing now.

The trust contract that makes a community function was always implicit. AI made it the most important thing to be explicit about. Communities that name the contract directly, and enforce it, will probably make it through. The ones that pretend nothing has changed will not.

I do not have this figured out for the communities I am part of. Honestly, I think most community managers are flying blind right now, and the tooling has not caught up.

The thing I am sure of is that "we will deal with it later" is not a strategy. The trust loss is happening now, quietly, in the gap between when a wrong answer gets posted and when somebody finally calls it out. Every gap like that is a small withdrawal from the community's credibility account.

If you run a developer community of any kind, this is the conversation worth having with your members in the next month or two. Not in a year.

Let Your LLM Think in English

2026-04-27T00:00:00Z

You ship a chatbot for your German team. The UI is German. The source docs are partly German, partly English. The tools behind the assistant expect English enum values, English function descriptions, English product names, English everything.

Then someone asks a perfectly normal question in German, the model picks the right tool, passes one argument in German instead of English, and the whole thing quietly falls apart.

I've seen versions of this enough times now that I no longer think of it as a translation issue. It is an execution issue.

My current default is simple: let users speak whatever language they want, but let the LLM do its retrieval, reasoning, and tool work in English whenever reliability actually matters. Then localize the answer outside that loop.

That sounds slightly heretical at first. It is also, in my opinion, the most practical thing you can do right now.

The research is starting to say this out loud

The numbers are not subtle anymore.

In the MASSIVE-Agents benchmark, researchers evaluated multilingual function calling across 52 languages, 47,020 samples, and 21 models. The best average score across all languages was just 34.05%. English reached 57.37%. Amharic dropped to 6.81%.

That is not a small quality wobble. That is a reliability cliff.

Then there is Lost in Execution, which gets even closer to the real systems problem. The paper shows that many multilingual tool-calling failures happen after the model already understood the intent and selected the correct tool. The dominant issue was parameter value language mismatch. In plain English, the model knew what to do, but expressed the executable bits in the user's language instead of the interface language, so the call failed anyway.

And this is not limited to tool calling. In Do Multilingual Language Models Think Better in English?, Etxaniz and colleagues found that self-translation into English consistently beat direct non-English inference across five tasks. Their phrasing is refreshingly blunt: models are "unable to leverage their full multilingual potential when prompted in non-English languages."

So yes, multilingual models are impressive. But if your bar is not "sounds pretty good" and is instead "must behave correctly in production," English still looks like the safer operating language remarkably often.

Why RAG breaks in the same place

People usually hear this argument and think of agents first. Function calling, structured output, API execution, that kind of thing.

RAG has the same weakness, just one layer earlier.

If your retrieval layer has to match a user's local phrasing against content written in mixed languages, with inconsistent terminology, translated product names, and half-localized taxonomy labels, you create more chances for the system to drift before generation even starts. Honestly, this is where a lot of "the model is unreliable" complaints come from. The model may be fine. The content interface is not.

I would rather normalize early.

Translate the question into English. Retrieve against an English canonical corpus. Let the model reason over one stable terminology layer. Generate an answer draft in English if needed. Then translate or localize the final response for the user.

That gives you one place where naming stays stable:

one canonical document title
one canonical product vocabulary
one canonical tool schema
one canonical set of retrieval labels

You can still support every user language on the outside. You just stop asking the core execution path to be perfectly multilingual at every step.

This is not anti-localization

Quite the opposite.

Bad multilingual AI architecture usually hurts local users first. They get the nice localized interface, then the hidden English-centric system underneath behaves inconsistently and makes them pay the price.

Proper localization means being honest about where language should flex and where it should not.

For me, the split looks like this:

Localize the UI, prompts, help text, onboarding, and final answers.
Localize the source content people read directly when that content needs to exist in-market.
Keep internal tool definitions, canonical identifiers, retrieval labels, and reasoning pivots in English if that is the most stable layer.
Add explicit post-processing or human review where a localized output has legal, regulatory, or contractual weight.

That last point matters more than teams like to admit. If the model is talking to a human, localization is a user experience decision. If the model is talking to another system, language is an interface contract.

Those are not the same thing.

The architecture I trust most right now

This is the version I would bet on today for multilingual AI products:

User asks in their language.
System translates or normalizes the request into English.
Retrieval, reasoning, ranking, and tool calls happen against English canonical data.
Final answer is localized back into the user's language.
High-risk outputs get an extra validation step before they leave the system.

It is not philosophically pure. It is operationally sane.

The nice thing is that recent research points in the same direction. Lost in Execution found that pre-translation of user queries generally reduced language mismatch errors better than post-hoc fixes, even if it still did not fully recover English-level performance. That matches what many builders already suspect in practice. If you wait until the end to clean up multilingual inconsistency, you are usually too late.

And yes, there are exceptions. If you are building for low-resource languages, domain-specific language, or culturally dependent phrasing, translating everything into English can introduce drift. The paper above explicitly warns about that. So do not turn this into dogma.

But as a default for enterprise copilots, internal assistants, multilingual RAG, and tool-using agents, I think the rule holds surprisingly well.

What this means in practice

This is exactly why I care so much about canonical content structure.

If your knowledge base has one clean source layer, stable terminology, and controlled localization on top, AI gets easier to trust. If every language version drifts independently inside the execution path, you are asking the model to improvise where your system should be precise.

this platform's whole approach is built around separating those concerns cleanly. Keep a canonical core. Localize deliberately. Track where variants exist. Do not pretend every layer of the stack should be equally multilingual just because the UI is.

I used to think the best multilingual AI experience meant "do everything in the user's language." I do not think that anymore. Not for systems that have to retrieve the right paragraph, choose the right tool, and return something you can trust.

The practical rule is simple: users should stay local, but the LLM's execution path should stay stable. Right now, that usually means English in the middle and localization at the edges.

That will change over time. I hope it changes quickly. But if you are shipping today and reliability matters more than aesthetics, I would let the model think in English and let your product speak the user's language.

Claude Design and the One-Person Creative Agency

2026-04-18T00:00:00Z

Yesterday Anthropic launched Claude Design, a new product from their Anthropic Labs team that lets you create designs, prototypes, presentations, and marketing collateral by talking to Claude. And I sat there looking at the announcement thinking: okay, so now one person with a Claude subscription genuinely has most of what a small creative agency offers. Design. Code. Automation. Presentations. Brand consistency. All inside the same ecosystem.

That's a wild sentence to write in 2026. But I don't think it is an exaggeration.

What Claude Design actually does

The short version: you describe what you need, and Claude builds a first version. Then you refine through conversation, inline comments, direct edits, or custom sliders that Claude generates for you. It is powered by Opus 4.7 and it is surprisingly good at maintaining visual consistency.

But the feature that caught my attention is the onboarding. During setup, Claude reads your codebase and existing design files to build a design system for your team. Colors, typography, components. Every project after that automatically follows your brand. You can import images, documents (DOCX, PPTX, XLSX), or point it at your codebase directly. There's a web capture tool that grabs elements from your live website so prototypes look like the real product.

Have a Figma mockup you want to iterate on? Export it, drop it into Claude Design, and start a conversation about what to change. Or just capture your existing website and say "make the hero section bigger and add a testimonial carousel." That kind of thing.

The testimonials from the announcement are telling. Brilliant's Senior Product Designer said their most complex pages, which took 20+ prompts to recreate in other tools, only required 2 prompts in Claude Design. Datadog's Product Manager described going from a rough idea to a working prototype before anyone leaves the room, and said what used to take a week of briefs, mockups, and review rounds now happens in a single conversation.

A week of back-and-forth, collapsed into one conversation. Think about that for a second.

The stack that changes everything

Here is where it gets interesting. Claude Design does not exist in isolation. Anthropic now has three products that, combined, cover an absurd amount of ground:

Claude Code: Write, review, and ship actual software. $2.5 billion in run-rate revenue as of February, responsible for an estimated 4% of all public GitHub commits worldwide.
Claude Cowork: Automate knowledge work. Research, analysis, document processing, recurring tasks from your desktop.
Claude Design: Create visual work. Prototypes, presentations, marketing collateral, brand-consistent assets.

And they hand off to each other. When a design is ready to build, Claude packages everything into a handoff bundle you can pass to Claude Code with a single instruction. Design to production in one flow. No Jira ticket. No handoff meeting. No "can you send me the specs in Slack."

I keep thinking about Sam Altman's prediction from early 2024 about the one-person billion-dollar company. At the time it sounded aspirational, maybe a little hyperbolic. The tools were not there yet. You could generate text and images, sure, but the gap between generating things and shipping real products was enormous.

That gap is shrinking fast.

What I would have given for this two months ago

When I built this platform, the marketing site was one of the most tedious parts. Not the code. The code was fine, Claude handles HTML and CSS like a champion. But the visual design decisions? The hero layout, the pricing page cards, the feature comparison tables? I described things in words, Claude produced something, and then I spent hours going back and forth trying to adjust spacing, colors, typography. All through text prompts. No visual feedback loop.

With Claude Design, that workflow becomes: "here is my website" (web capture), "redesign the pricing section to emphasize the team plan" (conversation), tweak the green accent color with a slider, approve, hand off to Claude Code for implementation. I estimate that would have saved me an entire weekend.

(Honestly, I'm a little annoyed it did not launch two months earlier.)

And the Canva export is clever. Canva has 220 million active users and $3 billion in annualized revenue. Anthropic is not trying to replace Canva. They're trying to be the place where ideas start before landing in Canva for final polish and distribution. That is a smart positioning play. You generate the creative in Claude Design, then export to Canva where your marketing team picks it up. Or export to PPTX for that investor deck. Or export as standalone HTML for a landing page.

The "just add tools" multiplier

This is the pattern I keep seeing across the AI space in 2026. The base model gets smarter, sure, but the real productivity jump comes from connecting tools together. Claude by itself is a very smart text generator. Claude with Code is a software engineer. Claude with Cowork is a research analyst. Claude with Design is a creative director. Claude with all three? That's a small agency.

And the connections keep growing. Anthropic said they will add more integrations over the coming weeks. MCP servers already let you connect Claude to external tools and data sources. The ecosystem is building itself.

For solo founders, freelancers, and small teams, this changes the calculus completely. You don't need a designer on retainer to produce professional-looking decks and prototypes. You do not need a separate frontend developer to turn mockups into code. You don't need a project manager to coordinate the handoff between design and engineering because there is no handoff. It is one continuous conversation.

I'm not saying designers are obsolete. Far from it. Brilliant and Datadog both described their designers using Claude Design. The tool makes good designers faster and gives everyone else access to competent visual output. That's a different thing from replacing people.

What this means for documentation products

This one I'm watching closely. In documentation products, visual quality matters. Entry pages need to look good. Quick-start guides need clear diagrams. Marketing docs need brand consistency across languages and teams.

A world where every team member can generate on-brand visual documentation, hand it off to a translation engine, and distribute it in seven languages without touching Figma or Photoshop or InDesign? That's exactly the workflow gap many documentation tools still have.

The part where it gets weirdly expensive

So here is the thing nobody is talking about yet. I created a brand new Anthropic account specifically to try Claude Design. Fresh account, no history, no prior usage. I imported one small Figma file and generated a single asset. That was it. Two operations. And I was out of credits.

On a brand new account. With a fresh allocation.

I don't know what the token math looks like on Anthropic's side when Opus 4.7 is doing visual generation, but whatever it is, it burns through credits at a pace that makes the "one-person creative agency" pitch feel a lot more expensive than expected. If importing a small Figma mockup and producing one image eats your entire budget, the economics of using this as your daily design tool don't work yet.

To be fair, this is a research preview and pricing will probably change. But right now there's a meaningful gap between the promise (replace your design workflow) and the reality (you might run out of credits before lunch). The productivity gains are real. Whether the credits-per-output ratio makes it practical for regular use is a different question entirely.

The honest caveat

Claude Design is in research preview. It will have rough edges. The testimonials are from design teams at well-funded companies with established design systems. Your mileage will vary, especially if you are starting from scratch with no brand guidelines to feed it.

But the trajectory is clear. Eighteen months ago you needed a designer, a developer, and a project manager to go from concept to shipped landing page. Today a single person with a Claude subscription can do a surprisingly credible version of that same workflow in an afternoon.

We are not at the one-person billion-dollar company yet. But the one-person creative agency? I think we just arrived.

One API Key, Many Tenants: Isolating DeepL Translations in a Multi-Tenant SaaS

2026-04-18T00:00:00Z

Every time I explain the translation architecture behind Rasepi to another developer, I get the same question: "Wait — all your tenants share one DeepL API key? How do you keep their glossaries and style rules from leaking into each other?"

It's a fair question. And the answer involves more design work than you'd expect.

I wrote about the full translation pipeline in a previous post — the block-level hashing, the orchestrator, the whole flow from document save to translated output. This post zooms into a specific sub-problem: how you take a third-party API that has no concept of tenants and build proper tenant isolation on top of it.

DeepL doesn't know about your customers

DeepL's API authenticates with a single API key. Everything created under that key — glossaries, style rule lists, translation history — belongs to the same account. There's no concept of "this glossary belongs to Customer A" on DeepL's side.

When you call GET /v2/glossaries, you get all glossaries from all tenants. When you create a style rule list, it lives in the same namespace as everything else. The API is flat.

For a self-hosted product where every customer runs their own instance with their own DeepL key, that's fine. For a multi-tenant SaaS where you manage the infrastructure? You need an isolation layer, and you need to build it yourself.

The database is the source of truth

My core design decision here: the database owns all glossary content and style rule configuration. DeepL is a runtime execution target, nothing more.

Every TenantGlossary and TenantStyleRuleList entity implements ITenantScoped, which means EF Core global query filters automatically scope all reads to the current tenant. A query for glossaries in Tenant A's request context will never return Tenant B's entries. This is the same isolation pattern I use everywhere in Rasepi, enforced at the ORM level — I didn't build anything special for translations specifically.

Here's what makes this interesting. When a tenant edits a glossary term, I do not immediately call DeepL. I update the database row and set IsDirty = true. That's it. The actual DeepL glossary gets created (or recreated) lazily, right before the next translation needs it.

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage);

    if (glossary?.Entries.Count == 0) return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty: delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var created = await _deepL.CreateGlossaryAsync(
        $"tenant-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = created.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync();

    return glossary.DeepLGlossaryId;
}

The query filter on TenantGlossaries does the isolation. The IsDirty flag does the lazy sync. The naming convention (tenant-{glossary.Id}) exists only for debugging in the DeepL dashboard — it has no functional purpose in the code.

Why lazy? Because DeepL v2 glossaries are immutable. You cannot edit them. Any change means delete and recreate. If a team imports a CSV with 200 terms and then fixes a typo in one entry, I don't want to delete and recreate the DeepL glossary twice. I just set IsDirty both times, and the single recreate happens when the next translation runs. Batching for free.

Style rules: same pattern, different API

DeepL's style rules are newer (v3 API) and actually mutable, which is nicer. You can update configured rules in place with PUT /v3/style_rules/{style_id}/configured_rules, and custom instructions can be individually added or removed.

I still use the same IsDirty pattern though, mostly for consistency. A TenantStyleRuleList has a DeepLStyleId that maps to DeepL's runtime identifier, plus ConfiguredRulesJson for the formatting rules and a collection of TenantCustomInstruction entries for free-text translation directives.

The real power is in those custom instructions. Each one is a plain-language directive, up to 300 characters, that shapes how DeepL translates. Some real examples I've seen work well:

"Always use 'Sie' form, never 'du'" — for formal German contexts
"Translate 'deployment' as 'Bereitstellung', never 'Deployment'" — context-dependent terms that go beyond simple glossary mappings
"Use British English spelling (colour, organisation, licence)" — when translating between English variants
"Put currency symbols after the numeric amount" — European formatting conventions

Each tenant can configure completely different instructions per target language, all behind the same API key. The isolation comes from the fact that every translation call includes only the glossary_id and style_id belonging to the requesting tenant. Other tenants' DeepL resources are never referenced — they're not even queried.

The translation call: everything composes

When the orchestrator translates a block, it assembles all tenant-specific settings into a single request:

var glossaryId = await _glossaryService
    .GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang);
var styleId = await _styleRuleService
    .GetOrSyncStyleIdAsync(targetLang);
var formality = langConfig.Formality ?? "default";

var options = new TranslationOptions
{
    GlossaryId = glossaryId,
    StyleId = styleId,
    Formality = formality,
    Context = documentContext,
    ModelType = styleId != null ? "quality_optimized" : null
};

Every parameter here is tenant-scoped. The glossaryId was resolved through a tenant-filtered query. The styleId was resolved the same way. The formality comes from TenantLanguageConfig, also tenant-scoped. Even the context — surrounding paragraphs sent to improve translation quality, which DeepL doesn't bill for — comes from the tenant's own document.

One thing worth noting: when style_id is set, DeepL automatically uses their quality_optimized model. You can't combine style rules with latency_optimized. That's a DeepL constraint, but honestly a reasonable trade-off. If you're investing in custom style rules, you probably want the best quality output anyway.

Block-level caching: your database as translation memory

I don't call DeepL for blocks that haven't changed. The caching mechanism is the TranslationBlock table itself.

Every source EntryBlock has a ContentHash — a SHA256 of its semantic content, with metadata attributes like blockId and deleted stripped out. Every TranslationBlock stores the SourceContentHash that was current when the translation was made. When the source block changes, its hash changes. The orchestrator compares hashes and only queues blocks with mismatches.

The decision tree for each block:

Hash matches, translation exists → skip (cached, up-to-date)
Hash changed, machine-translated, not locked → retranslate automatically
Hash changed, human-edited or locked → mark as Stale, do not overwrite

That third case matters a lot. If a translator manually refined a paragraph, I don't want to blow it away just because the English source changed. Flag it as stale so the team knows it needs review, but leave the translated text intact.

The practical result: editing one paragraph in a 30-paragraph document triggers exactly one DeepL API call (one batch, one block). The other 29 paragraphs across all languages are already cached. They don't cost anything.

Why not give each tenant their own key?

I considered it. Give each tenant their own DeepL API key, eliminate the isolation problem entirely.

Three reasons I didn't go that route:

Billing complexity. Every tenant would need their own DeepL subscription or a way to provision sub-accounts. DeepL doesn't offer multi-tenant key management natively. Managing that onboarding flow is more overhead than building an isolation layer.
Cost efficiency. Shared infrastructure means shared volume. Aggregate usage gets better pricing than dozens of individual small accounts.
Operational simplicity. One key to rotate, one quota to monitor, one integration to maintain. That's genuinely valuable.

The trade-off is that you need the isolation layer I described. But if you already have tenant-scoped EF Core queries for everything else in your system — which you should — adding it to glossaries and style rules is straightforward. You're applying an existing pattern, not inventing a new one.

What actually isolates what

To summarize the guarantees I rely on:

Glossary entries are stored in TenantGlossary (implements ITenantScoped), filtered by EF Core global query filters. DeepL glossary IDs are opaque references that only get resolved within tenant context.
Style rules and custom instructions follow the same pattern through TenantStyleRuleList.
Translated content lives in TranslationBlock, scoped via its parent Entry → Hub chain, which is also tenant-scoped.
The SaveChanges guard sets TenantId automatically on new entities and throws on cross-tenant writes.
No IgnoreQueryFilters() in production code.

DeepL sees resource IDs. My application sees tenant-scoped entities. The mapping between them never crosses tenant boundaries because the query that resolves the mapping is physically incapable of returning another tenant's data.

If you're building a multi-tenant SaaS on top of third-party APIs that weren't designed for multi-tenancy — and there are a lot of them — this approach works well. Treat the external API as a stateless execution engine. Keep all configuration in your own tenant-scoped database. Sync lazily. And never trust external resource listings for isolation, because those listings are flat.

Tokens Burned Is the New Lines of Code

2026-04-13T00:00:00Z

My LinkedIn feed has been full of it for weeks. My X timeline too. People posting token spend screenshots like they're progress reports. Startup founders bragging they spent $16k on Claude Code last month and are aiming for $60k next. Leaderboards. Rankings. Titles like "Token Legend" and "AI God."

And then last week, it hit critical mass. Forbes reported on the "tokenmaxxing" movement sweeping Silicon Valley, where companies compete to see who burns the most AI tokens. Jensen Huang went on the All-In podcast and said: "That $500,000 engineer, at the end of the year, I'm going to ask him, 'How much did you spend in tokens?' If that person says '$5,000' I will go ape-something else. If that $500,000 engineer did not consume at least $250,000 worth of tokens, I am going to be deeply alarmed."

Then Fortune reported that a Meta employee had built an internal leaderboard called "Claudeonomics" tracking token consumption across the company's 85,000+ staff. Top users got titles. In a 30-day window, total usage hit 60 trillion tokens. The top individual user averaged 281 billion. Mark Zuckerberg didn't even crack the top 250. Meta CTO Andrew Bosworth, meanwhile, was publicly saying his best engineer was spending his salary equivalent in tokens but running "5x to 10x more productive." "It's like, this is easy money," Bosworth said. "No limit."

I've been in software long enough to recognize what's happening here. This is "lines of code" with a much higher price tag.

We've been here before

In 2003, Martin Fowler wrote a short piece on why software productivity cannot be measured that should probably be required reading for every technical executive. His argument on lines of code was precise:

"One of my biggest irritations are studies of productivity based on lines of code. Any good developer knows that they can code the same stuff with huge variations in lines of code."

The problem is obvious once you say it out loud. LOC measures activity, not output. Two developers can build the same feature: one writes 1,200 lines, the other writes 80. The concise one probably built a better system. Under a LOC regime, the verbose one looks more productive.

Teams evaluated on LOC responded rationally. They wrote more lines. They copy-pasted rather than abstracting. They avoided refactoring because deleting code would hurt their numbers. The metric shaped behavior, but not toward better software. More code. Worse systems.

Then in 2023, McKinsey published a piece claiming to have cracked objective developer productivity measurement. Gergely Orosz and Kent Beck's thorough response pointed out the same flaw: nearly every McKinsey metric was measuring effort and output, not outcomes. Kent Beck recounted watching Facebook's internal developer sentiment surveys devolve from useful feedback into managers negotiating with engineers for higher scores. That's what happens when you incentivize a proxy metric. The number improves. The thing you actually cared about does not.

You'd think we would have learned. We haven't.

Same mistake, different unit

The seductive logic of tokenmaxxing runs like this. Token consumption = AI usage. More AI usage = teams are using AI. Therefore, high token spend = high AI adoption = good.

It is precisely as flawed as measuring lines of code, just with a billing dashboard instead of a commit graph. And to be fair to the Forbes article, Sendbird's CEO John Kim basically said exactly that: "We've seen this movie before." He was referring to the 1990s and 2000s LOC culture. The real indicator, he noted, is how much AI-generated code actually makes it into production. Token spending "is more of a conversation starter." I agree with that. It becomes a problem when the conversation starter gets promoted to the headline KPI.

GitHub's 2024 developer survey found that 97% of enterprise developers had used AI coding tools at work at some point. Meaningful organizational adoption, though, required clear policies, workflows, and measurable outcomes tied to actual business results. Not just usage. Not just consumption.

Boris Cherny, the engineer behind Claude Code, publicly shared that he didn't open an IDE at all during one month of work, with Opus 4.5 writing around 200 PRs. That's impressive. But what makes it impressive is not the tokens those 200 PRs consumed. It's that they were 200 real merged contributions with working software on the other end.

The value is in the outcome. Tokens are the energy that got you there, nothing more.

When the metric becomes the target

There's a principle called Goodhart's Law: when a measure becomes a target, it ceases to be a good measure. The history of software development is basically a museum of Goodhart's Law in action.

Tracking tokens as an AI adoption KPI sets up the exact same dynamic. Engineering teams measured on token consumption will consume more tokens. That's just how incentives work. Want to look more productive? Run a few more agentic loops. Let the model reason at length before generating output. Wrap every task in an orchestration layer that calls four tools where one would do. Token spend goes up. Value delivered does not.

Actually, the Claudeonomics story proved this almost immediately. Fortune noted that "some employees have put AI agents to work for hours to maximize their token usage." There it is. Goodhart's Law executing in real time, inside a company that's supposed to be at the frontier of AI-driven productivity. The leaderboard had been up for maybe a few weeks before it was shut down, and employees were already gaming it by running agents in loops. The metric was three weeks old and it had already stopped measuring what it was supposed to measure.

Any developer reading this can probably think of five ways to inflate token usage metrics at no benefit to anyone. I won't list them. But if I can think of five, so can the engineers being measured on this.

Andrej Karpathy described the current moment in software engineering as a "magnitude 9 earthquake" for the profession. He's right. But earthquakes don't get measured in the electricity consumed. They get measured in what moved.

The documentation version of this problem

This isn't only a problem for engineering teams. The same dynamic shows up in knowledge management too.

"We published 400 documents this quarter" is a number that sounds good in a slide deck. It has nothing to say about whether those documents are accurate, whether anyone read them, or whether the information in them is still true six months later. You can hit that number with AI and no thinking whatsoever. Token-assisted noise published at scale.

The honest metric is harder to collect but much more useful: what percentage of your knowledge base actually reflects how your systems work today? How many people reached a correct answer using your documentation? How many tried, failed, and ended up asking someone on Slack instead?

Those questions don't have pretty dashboards yet. They require actual thought about what you want documentation to do for your organization. Forced expiry dates, for example, exist so teams have to reckon with whether content is still valid, rather than letting it silently decay behind a high page-count metric.

What to track instead

The honest answer to "is our AI investment paying off?" cannot be read from a billing dashboard.

You can approximate it with better questions: are cycle times improving? Is the ratio of features shipped to bugs reported trending in the right direction? Are engineers reporting they spend more time on judgment-heavy work and less on typing? Is your documentation staying current instead of accumulating like sediment?

These are harder to pull from an API. They require thinking about what output you actually want from your teams, which, admittedly, is the harder work. But they're the questions that matter, because they're about outcomes rather than inputs.

Token spend tells you how much compute you bought. Whether that compute became something useful is an entirely separate question. Companies that don't maintain that distinction are going to build very expensive dashboards that show them almost nothing.

We spent years optimizing the wrong metric for developer productivity. We have maybe one quarter before the same mistake gets baked into every AI adoption report in the enterprise. The window to avoid this is open, but it won't stay that way.

The AI Divide Is Splitting Your Team in Half

2026-04-10T00:00:00Z

I was on a call last week with a friend of mine who told me about one of their customers, a logistics company. A team lead there had a planning meeting where two of her people had built an entire scenario model using AI before the meeting even started. Forecasts, risk breakdowns, three alternative approaches. The other four people on the team showed up with the same slide deck format they've been using for two years. Same structure, same manual process, same timeline estimates.

The meeting went sideways fast. The AI-assisted pair couldn't understand why the others hadn't done basic prep that "takes five minutes now." The others felt ambushed, like the rules of the game changed and nobody told them. The team lead spent the rest of the day doing damage control.

That story doesn't surprise me anymore. I've been hearing versions of it for months.

The gap is measurable now

This isn't just vibes. Microsoft's 2025 Work Trend Index, a survey of 31,000 workers across 31 countries, found that 67% of leaders are familiar with AI agents, compared to just 40% of employees. Leaders are far more likely to see AI as a career accelerator (79% vs. 67% of employees), and they're saving more time with it, too. Nearly a third of leaders say AI saves them over an hour every single day.

But here's the part that really stuck with me: when asked how they see AI, 52% of respondents said they treat it as a command-based tool. Give it an instruction, get a result. Only 46% described it as a thought partner, something you have a back-and-forth with.

That's not a small difference. That's two fundamentally different relationships with the same technology. And those two groups are sitting in the same meetings, working on the same projects, supposedly moving in the same direction.

Two speeds, one team

The practical consequence is that teams are now operating at two completely different speeds. The people who've integrated AI into their daily work don't just produce faster. They think differently. They approach problems differently. They arrive at meetings with work that used to take a week done in an afternoon.

And the people who haven't adopted AI (or who've tried it once, found it underwhelming, and moved on) are doing genuinely solid work. I want to be clear about that. It's not that they're bad at their jobs. It's that the ceiling of what's possible has moved, and they're working under the old one.

A Harvard study on generative AI in teams found something remarkable: a single individual with AI outperforms an entire team without it. But a team where everyone uses AI outperforms them all. The implication is brutal. Mixed adoption doesn't give you a middle ground. It gives you friction.

I saw this firsthand at a workshop I ran last month. The participants who used AI regularly were finishing exercises in half the time, then getting frustrated waiting for the rest. The participants who didn't use AI felt rushed and, honestly, a bit humiliated. Nobody intended that outcome. It just happened because the speed gap is that large now.

The competitive advantage nobody talks about

Here's where it gets really consequential. McKinsey's State of AI 2025 survey found that 88% of organizations are using AI in at least one function. Sounds great, right? But nearly two-thirds are still stuck in experimentation and pilot phases. Only about a third have begun scaling AI across their business. And the companies that have scaled, the ones McKinsey calls "high performers"? They represent roughly 6% of respondents.

That 6% is pulling away from everyone else at a speed that I think most people underestimate.

High performers are three times more likely to have fundamentally redesigned their workflows around AI. They're three times more likely to have senior leaders actively championing and role-modeling AI use. Three-quarters of them are scaling or have already scaled AI across their organization, compared to one-third of everyone else.

Microsoft's data tells a similar story. Companies they call "Frontier Firms" (those with org-wide AI deployment and advanced maturity) report dramatically different outcomes. 71% of Frontier Firm leaders say their company is thriving, compared to 39% of workers globally. 55% say they can take on more work, versus 25% globally. And they're less afraid of AI taking their jobs, not more.

The gap between these companies and everyone else isn't narrowing. It's accelerating.

This is a people problem disguised as a technology problem

The temptation is to solve this with tools. Roll out Copilot, buy some licenses, send a company-wide email about AI resources. Done.

But the actual challenge is cultural. It's the team lead on that call trying to hold together a group where half the people feel supercharged and the other half feel left behind. It's the manager who has to explain to a 20-year veteran that their workflow, the one they perfected over a decade, might not be the best approach anymore. It's the junior employee who's quietly using AI to produce senior-level work and doesn't know whether to be proud or worried about political fallout.

Microsoft found that 47% of leaders list upskilling existing employees as a top workforce strategy. That's encouraging, I guess. But upskilling only works if people actually want to learn. And right now, a meaningful chunk of the workforce has decided that AI is either not relevant to them, not reliable, or not worth the effort. Some of them might be right about specific tools. But the broader trajectory isn't optional (I say that as someone who's been skeptical of plenty of tech hype cycles over the years, and this one feels different).

Where this is heading

I don't think the divide goes away. I think it widens. The people who adopt AI will keep getting faster, keep producing more, keep raising the bar for what "normal output" looks like. The people who don't will feel increasing pressure, whether from management, from peers, or just from the ambient reality that their colleagues are doing things they can't.

Companies that figure out how to bring their whole team along, not just the enthusiasts, will have a genuine advantage. And that advantage compounds. Every month of organizational AI fluency is a month your competitors spend arguing about whether to buy ChatGPT licenses.

The biggest competitive advantage in the AI era won't be which model you use. It will be whether your entire team actually uses it.

That logistics team I mentioned? My friend told me the team lead booked a two-day internal workshop. Not "here's how to prompt." More like "here's how this changes the way we plan together." The skeptics needed to see what was possible in the context of their work, not in some generic demo with a made-up scenario. And the enthusiasts needed to learn patience. To bring people along instead of running ahead.

That feels like the job right now. Not just adopting AI. Closing the gap. Before it closes you.

Build vs Buy Reimagined: What It Actually Means in 2026

2026-04-07T00:00:00Z

Last week I watched a junior developer on our team spin up a working CRUD app with auth, database migrations, and a halfway decent UI in about 90 minutes. With Copilot. From scratch.

Five years ago, that same task would have taken a week. Maybe two if you count the yak-shaving around deployment configs and OAuth flows. And that shift, that compression of building time from days to hours, is quietly dismantling one of the oldest questions in software: should we build or should we buy?

The Old Framing is Dead

For decades, "build vs buy" was a cost calculation. You'd estimate how many developer-months it would take to build a thing, multiply by loaded salary, add some buffer for maintenance, and compare it to the annual license fee of whatever SaaS product did roughly the same thing. If the SaaS was cheaper, you bought. If your requirements were weird enough, you built.

That framing assumed building was expensive. And it was. But according to GitHub's Octoverse 2025 data, AI-assisted development now produces a 20 to 30 percent increase in throughput. Eighty percent of new developers on GitHub use Copilot within their first week. Over 1.1 million public repositories already integrate LLM SDKs. Building got dramatically cheaper, almost overnight.

So the question isn't really "build vs buy" anymore. It is something more like: what are you actually paying for when you buy SaaS?

The New Calculus

Here's what I think most SaaS founders (myself included, honestly) don't want to hear: if your entire value proposition is "we saved you from building it," you're in trouble. Because that moat just got a lot shallower.

When a team can prototype a functional internal tool in a day, the bar for what justifies a monthly subscription goes way up. You do not just need to be better than what they could build. You need to be better than what they could build with AI helping them.

Gartner predicted in April 2026 that by 2028, over half of all enterprises will stop paying for assistive intelligence and favor platforms that commit to workflow results. Even more stark: they expect that by 2030, software companies layering bolt-on AI over legacy applications rather than redesigning for agentic execution will face margin compression of up to 80%.

Eighty percent. That is not a rounding error.

So What Actually Survives?

I have been thinking about this a lot, partly because I'm building this and I need to be honest with myself about where our value sits. And I think the answer comes down to three things that are genuinely hard to replicate with a weekend coding sprint, no matter how good your AI assistant is.

Domain depth you can not fake. Anyone can build a text editor. Building a translation system that tracks content changes at the paragraph level, detects stale translations through content hashing, and handles structural adaptation across languages? That takes years of domain knowledge baked into architecture. The AI can help you write the code faster, but it can not tell you what to build.

Someone still has to run and maintain it. Here is the thing about building: it is fun. Maintaining? Not fun at all. Handling edge cases in multi-tenant permission systems, keeping up with browser quirks, managing database migrations across versions, patching CVEs at 2am, dealing with that one PDF export bug that only shows up in Safari. AI makes the initial build faster, sure. But Forrester's April 2026 research shows most enterprises still can not turn AI adoption into measurable impact, partly because the hard part was never writing code. It is keeping the thing running, updated, and working correctly for years. The build is the easy part. It's the uptime, on-call rotations, and incremental fixes that actually cost you.

Trust, security, and data privacy. This one is underrated. When you build something yourself, you own security. You're responsible for encryption at rest, audit logging, penetration testing, GDPR compliance, SOC 2, and the next regulation nobody has heard of yet. A good SaaS vendor has an entire team whose only job is making sure your data does not end up somewhere it should not be. For most companies, that is not a cost they want to carry internally. And honestly, most internal tools I have seen do not even have proper access controls, let alone a security audit trail.

The Composable Middle Ground

What is interesting is that the answer increasingly is not "build" or "buy." It is compose. Pick the SaaS tools that do hard things well, expose good APIs, and let you build around them.

This is why plugin architectures matter so much right now (and yes, this is exactly what we've been investing in with this platform's plugin system). The SaaS products that will thrive are the ones that say: "We handle the hard, domain-specific core. You customize everything else." Not "here's our monolith, take it or leave it."

Forrester's April 2026 report found that most enterprises are still struggling to turn AI adoption into measurable business impact. High adopters are 47% more likely to work with consulting partners to prepare their data and systems. The message is clear: raw building capability is not the bottleneck. Knowing what to build, and having the infrastructure to support it, that's the actual constraint.

What This Means for SaaS

If you're running a SaaS company in 2026, I think there are a few uncomfortable truths:

Your "we'll save you time" pitch is weaker than ever. Time savings was the classic SaaS sell. But when AI compresses build time by 20-30%, the "time saved" number in your ROI spreadsheet shrinks proportionally. You need a different story.
Features are table stakes, outcomes are the product. Nobody cares that you have 47 integrations. They care that their documentation stays fresh, their translations stay accurate, their team actually uses the tool. Gartner's language about "outcome-focused workflow" is not just analyst jargon. It is where the market is heading.
Openness beats lockdown. The instinct to close your platform and make switching hard is understandable. But Gartner explicitly warned that "legacy SaaS providers that attempt to close systems of record risk being bypassed by orchestration layers enterprises trust more." Ouch.

The Honest Version

I will be blunt about where I land on this. Build vs buy was never really about the technology. It was always about trust. Do I trust this vendor to understand my problem deeply enough that their solution will be better than what I could cobble together?

In 2026, "cobble together" got a massive upgrade. So the trust bar went up too.

For documentation vendors, that means you can't just be a tool that happens to support translations. You have to be deeply good at the hard problems, block-level translation tracking, content freshness enforcement, and multi-tenant complexity, so replacing your product is genuinely painful even with the best AI tools in the world.

That is the new build vs buy. Not "can you build it?" but "should you spend your energy building it when someone else has already solved the hard parts?"

The question was never really about cost. It was about where you want to spend your attention. And in a world where building is cheap, attention is the only scarce resource left.

Three Weeks, One App: What AI Can Build For You and What It Absolutely Cannot

2026-04-05T00:00:00Z

Three weeks ago I had a .NET backend with maybe 40% of the services wired up, a half-finished Vue frontend, and a vague plan. Today this platform has a block-level translation engine with glossary management and style rules, a freshness scoring system with expiry templates and review workflows, AI-powered semantic search with RAG, a full plugin SDK with action guards and event pipelines, collaborative real-time editing, a complete marketing website with pricing pages, a developer documentation portal, a blog with 14 posts, automated translations into 7 languages, and a waitlist form that actually sends emails.

I did not do this alone. I had Claude running in VS Code every evening for hours and sometimes all day even, and it was genuinely transformative for the parts it could help with. But there's a chasm between "building an app" and "having something you could actually sell to another human being," and that chasm is filled with tons of setup pages, manual configuration, email deliverability settings, and DNS records. Claude just can't talk to all these services yet.

People rarely talk about that part.

Could I Have Done This Without AI?

Look, I have over 30 years of experience building software. Could I have built all of this without Claude? Probably. But not in three weeks. Not even close. The AI accelerated everything that involves typing code into files, and that is a massive part of any project.

But here's the thing people miss when they talk about "vibe coding" and building entire apps with AI: you still need to know what you're doing. Claude can tell you every single step required to deploy a Cloudflare Worker with a D1 database. It can walk you through OpenIddict configuration. It can explain DNS records and SPF setup. The problem is that its knowledge is often outdated. Platforms update their dashboards, move settings around, deprecate features, rename things. And Claude doesn't know.

I didn't even use only one AI. ChatGPT occasionally knew more about specific services, especially when Claude's training data was a few months behind on a particular platform's documentation. Some days I had both open side by side, cross-referencing their suggestions against what I was actually seeing in the dashboard.

And then there's Codex. I used OpenAI's Codex frequently to analyze the codebase from the outside. Not to write code, but to review it. Having a different agent look at code that Claude wrote catches things that Claude itself is blind to. It's like having a second pair of eyes on a pull request, except both reviewers are AI and neither of them gets offended. I'd point Codex at a service layer and ask "what's wrong with this?" and it would find issues that Claude had confidently introduced three sessions ago. Different models have different blind spots, and running them against each other produces genuinely better results than trusting any single one.

But the deeper point is this: to have a sellable app, you absolutely need to know how hosting works. How domains work. How code signing certificates work. How databases work. How email deliverability works. How OAuth2 flows actually function, not just the code that implements them. Can you build an app without that knowledge? Sure. Will it get you anywhere? Likely not. You'll have something that runs on localhost and impresses nobody outside your own machine.

The 80% That Felt Like Magic

Let me be clear about what worked, because it genuinely worked well. For churning out service interfaces, implementing CRUD controllers, writing EF Core configurations, and building Vue components, Claude is absurdly fast.

Here's an example. When I needed to add the glossary management system, I described the requirement: tenant-scoped glossaries, CSV import/export, individual term CRUD, and a sync mechanism with DeepL's glossary API. Claude produced the entity models, the service interface and implementation, the controller with proper authorization attributes, and the Pinia store. All in maybe 20 minutes. Would have taken me most of a day to write all that by hand.

The translation engine was similar. The block-level architecture with SHA256 content hashing, the staleness detection, the orchestrator that coordinates between services. Claude understood the pattern after I explained it once and then replicated it consistently across dozens of files. The freshness scoring system, the review workflows, the expiry notification pipeline. Service after service, wired up and working.

For the marketing site, Claude built entire HTML pages from descriptions. "A pricing page with a free tier, a team tier, and an enterprise tier. Dark background. Use the green accent." And it just... produced one. Including responsive breakpoints and hover states.

That's the magic part. It is real.

Taming the Machine

But it's not like I just typed "build me an app" and walked away. Working with Claude is its own skill, and I spent the first few days doing it badly.

The initial output is always... fine. Technically correct, reasonably structured, but generic. Claude writes code the way it writes prose: competent, predictable, and deeply average. Left to its own devices, it'll produce the same controller structure every framework tutorial uses. The same service pattern. The same component layout. It works, but it's not yours.

So you start to train it. Not formally, not with fine-tuning, but through repetition and correction. "No, I want the service interface separate from the implementation." "Always use this authorization attribute pattern." "The tenant context comes from middleware, not from the request body." Turn after turn after turn. Some days I felt like I was pair programming with a very enthusiastic junior who keeps forgetting what we decided yesterday.

And then something clicks. After enough corrections, after enough examples in the codebase for it to read, Claude starts getting it right on the first try. It picks up your naming conventions. It knows where you put your DTOs. It follows your error handling pattern without being asked. That transition from "annoying" to "productive" took maybe four or five days of consistent work.

The blog posts were a similar story. Claude's default writing voice is instantly recognizable. That polished, slightly distant, perfectly structured style that reads like every AI-generated blog post you've ever seen. I went through multiple rounds building a style guide, feeding it examples of how I actually write, pointing out every "it's worth noting" and every em dash (seriously, the em dash addiction is real). Eventually I built a whole skill file, a set of instructions that Claude loads before writing anything for the this platform blog.

This post, for the record, is Claude. With my input, my corrections, my direction. I described what I wanted to say, pointed it at the style guide, and then spent time going back and forth until the voice felt right. That's the actual workflow. Not "AI writes it" and not "I write it." It's a conversation that produces something neither of us would have written alone.

I also built custom instructions for the codebase itself. A copilot-instructions file that explains the architecture, the translation system, the tenant isolation rules, the coding conventions. Claude reads this at the start of every session, and the difference is night and day. Without it, Claude guesses. With it, Claude knows.

The point is: the productivity gains are real, but they're not free. You invest time upfront teaching the AI how you work, and that investment pays off over weeks. Skip that step and you'll spend more time fixing Claude's output than you would have spent writing the code yourself.

When the Machine Fights You

I don't want to paint too rosy a picture here. For every session where Claude nailed a complex service implementation in 20 minutes, there was another session where it drove me up the wall.

The worst habit is re-introducing bugs that were fixed days ago. You spend an evening tracking down a race condition in the SignalR hub, you fix it, you move on. Three days later Claude is editing a nearby file and quietly puts the old broken pattern back. Not maliciously, obviously. It just doesn't remember. Every session starts fresh, and if the fix wasn't obvious from the code alone, Claude will happily revert to whatever pattern its training data prefers. I learned to write very explicit comments above tricky fixes. Not for future developers. For future Claude.

Then there's the circling. You ask Claude to fix a failing test. It changes something. The test still fails. It changes something else. Still fails. It reverts the first change and tries a third thing. Then it combines the first and third changes. Then it goes back to the second approach but with a slight variation. Thirty minutes later you've watched it try nine permutations of the same wrong idea and not once did it stop to reconsider whether the whole approach was off. I've had sessions where I finally said "stop, let me look at this" and found the actual issue in about two minutes. It was a one-line fix. Claude had spent half an hour rearranging deck chairs.

And the confidence. Claude never says "I'm not sure about this." It presents every suggestion with the same calm authority, whether it's a perfect solution or complete nonsense. After a while you develop an instinct for when it's guessing, but early on I wasted real time implementing suggestions that sounded reasonable and turned out to be hallucinated API methods or deprecated configuration patterns.

This is exactly why I started using Codex to review Claude's output. And it's why the experience argument matters so much. A junior developer wouldn't catch these regressions. They wouldn't recognize the circling. They'd trust the confident hallucination. Thirty years of knowing what correct code looks like is the difference between AI as a productivity multiplier and AI as a very fast way to create technical debt.

Then You Need to Actually Deploy the Thing

Here is where the story changes.

You have a working application on localhost. Beautiful. Now put it on the internet. Make it send emails. Let people sign up. Accept payments eventually. Protect it from bots. Give it a domain name that resolves correctly.

Claude cannot help you with any of this. Not really.

I don't mean it produces bad suggestions. I mean it fundamentally cannot interact with the systems you need to configure. And the configuration is where you spend your time, not writing code.

Cloudflare: A Case Study in "Figure It Out Yourself"

this platform's marketing site runs on Cloudflare Pages. The waitlist API is a Cloudflare Worker with a D1 database. Sounds straightforward until you actually have to set it up.

Claude has never seen your Cloudflare dashboard. It can tell you "add a CNAME record" but it cannot tell you which of the 14 tabs contains the DNS settings for your particular domain. D1 database bindings need a specific database ID in your wrangler.toml. Environment secrets go through wrangler secret put. CORS has to match your actual deployed origins, not localhost. Turnstile needs keys from yet another dashboard section.

I spent almost an entire day getting the Worker to correctly verify Turnstile tokens, accept form submissions, store them in D1, and send confirmation emails. Claude helped me write the Worker code itself. But the deployment, the wrangler configuration, the secret management, the DNS propagation debugging? That was all me.

OAuth2: The Configuration Labyrinth

Authentication is the best example of the gap between "code" and "product."

Claude can absolutely write you an OAuth2 integration. It knows the OIDC spec, it can produce middleware, it understands JWT claims. For our dev environment I have a DevAuthHandler that mints tokens with tenant_id and sub claims from a simple bearer string pattern. Claude wrote that in minutes.

But production auth means OpenIddict, and OpenIddict means figuring out sub claims, tenant_id claims, callback URLs, JavaScript origins, logout URIs, and all the other shenanigans that come with a real identity setup. And that's before you even get to the external providers.

Because your users want to log in with Google, Microsoft, or GitHub. And Claude can't log into any of those developer consoles for you. It cannot:

Create an OAuth application in the Google Cloud Console and generate a client ID and secret
Register an app in the Microsoft Entra portal and configure the redirect URIs
Set up a GitHub OAuth App and grab the credentials
Configure each provider's callback URLs for every environment you run
Wire up the correct scopes, consent screens, and token endpoints

Each provider has its own developer portal, its own terminology, its own flow for generating credentials. Google calls it a "consent screen." Microsoft calls it "app registrations." GitHub calls it "OAuth Apps" (not to be confused with "GitHub Apps," which are a different thing entirely). And every single one of them requires you to manually copy a client ID and secret into your configuration.

Claude can write the OpenIddict server configuration, the external provider middleware, the claim transformation logic. But the actual credential generation, the portal navigation, the environment-specific URL setup? That's all you, in a browser, clicking through dashboards.

Email: It's Never Just "Send an Email"

The code to send an email via the Resend API is about 15 lines. Claude wrote it without issue. But making emails actually arrive in someone's inbox? That requires a verified sending domain, DNS records for SPF, DKIM, and DMARC, waiting for propagation, and then testing deliverability because Gmail and Outlook have their own opinions about whether your domain is trustworthy.

And designing an email template that doesn't look terrible in every email client. Outlook on Windows still uses the Word rendering engine in 2026. Let that sink in.

The Full List of Things I Did Without AI

Looking back at three weeks of work, I started keeping a rough mental tally of what Claude built versus what I configured by hand. The "by hand" list is longer than I expected:

Cloud Infrastructure:

Cloudflare Pages project setup and custom domain configuration
Cloudflare Worker deployment and D1 database provisioning
DNS records for marketing site, API, and email sending
SSL/TLS certificate configuration (mostly automatic, but debugging when it's not is painful)
Build pipeline configuration for the blog (Eleventy + translation + OG image generation)

Authentication & Security:

Google, Microsoft, and GitHub OAuth app registration and credential generation
OpenIddict configuration with correct claims, callback URLs, JS origins, and logout URIs
Turnstile bot protection setup (site keys, secret keys, dashboard config)
CORS policy configuration between frontend, API, and Worker origins

Email:

Resend account and API key setup
SPF, DKIM, DMARC DNS records
Email deliverability testing and troubleshooting
Template testing across email clients

Third-Party Integrations:

DeepL API account and key management
Google Analytics setup with cookie consent integration

Azure Hosting:

Azure App Service setup and configuration for the .NET backend
Azure SQL database provisioning, firewall rules, and connection strings
Azure Cache for Redis setup and connection configuration
Azure OpenAI resource provisioning for embeddings and RAG

Deployment:

Docker configuration for the .NET backend
Environment variable management across three different deployment targets
Database connection strings for different environments

And honestly I'm probably forgetting a few things. Every third-party service has its own dashboard, its own credential model, its own documentation quality (varying wildly), and its own quirks.

Why This Matters More Than People Think

Here's the dimension that gets lost in every conversation about AI-assisted development: AI tools have zero context about your infrastructure.

Your codebase lives in files that an AI can read. Your Cloudflare configuration does not. Your Google OAuth app settings do not. Your DNS records do not. Your Resend domain verification status does not. The entire operational surface area of a real product is invisible to AI tools, and that surface area is enormous.

Writing code is the easy part of software engineering, and it's getting easier by the day. The hard parts are what you do with that code. Operating it, understanding it when something breaks at 2am, extending it when requirements change, and governing it across its entire lifecycle. AI makes the easy part faster. It does nothing for the hard part.

The Marketing Site Deserves Its Own Section

I built the entire this platform marketing site in roughly four days. Homepage, pricing page, signup and contact forms with bot protection, privacy policy, four feature deep-dive pages. Claude did probably 70% of the HTML/CSS.

But then I needed it to actually exist on the internet. The blog runs on Eleventy with an 8-step build pipeline: translate posts via DeepL, build the site, translate static HTML pages, copy shared assets, generate OG images from SVGs, generate audio versions, manage audio manifests, produce a multilingual sitemap. Claude helped write pieces of that pipeline, but getting it all to work together with the right file paths and the right Cloudflare Pages deployment settings took a full day of trial and error.

And the developer documentation site? That's a separate Cloudflare Pages project with its own domain, its own build config, and its own deployment triggers. Another dashboard, another set of environment variables, another round of DNS.

The Pattern I Keep Seeing

For any given feature, Claude handles about 80% of the work by volume. Lines of code, files created, problems solved. But the remaining 20% is entirely manual configuration work: clicking through web dashboards, copying keys between services, debugging integration issues that only show up in deployed environments.

And that 20% takes at least as long as the other 80%. Sometimes longer.

But here's the thing that changed compared to how solo development used to work: in the past, you were either writing code or doing config. Never both. If you spent a day setting up Stripe webhooks and testing payment flows in their dashboard, that was a day you wrote zero application code. Your project just stopped moving forward on one front while you worked on the other.

With Claude, that's no longer true. While I was deep in the Stripe dashboard figuring out webhook endpoints and event types, Claude was building out the next service interface. While I was clicking through Google's OAuth consent screen setup for the third time because I got the scopes wrong, Claude was writing Vue components. My head was in configuration land, but the codebase kept growing. That's genuinely new. A solo developer can now move on two fronts at once, and that might be the biggest practical difference AI makes for small teams.

That said, when you're writing code with AI help, you're in a tight feedback loop. Write, test, fix, iterate. When you're debugging why your Cloudflare Worker returns CORS errors only in production, you're staring at dashboard screenshots, reading community forum posts, and trying random configuration changes hoping one of them sticks.

What Needs to Change

I do not think this is a permanent limitation. The missing piece is obvious: AI tools need to be able to interact with third-party service APIs and dashboards. Not just write code that calls them, but actually configure them.

Some of this is starting to happen. MCP (Model Context Protocol) servers for various services are popping up. Anthropic is clearly thinking about tool use as a first-class concept. But we're nowhere near the point where I could say "set up my Cloudflare Worker with a D1 database, configure the custom domain, and add Turnstile protection" and have it actually happen.

Until then, the honest story of building a product with AI is this: AI is an incredible accelerator for writing application code. But a sellable product is only about half application code. The other half is infrastructure, third-party integrations, deployment pipelines, email deliverability, domain configuration, and security setup. And for all of that, you're on your own.

(This is, incidentally, one of the reasons I'm building this as a hosted platform and not just shipping open-source code. Getting documentation software to run is not that hard. Getting it to run reliably, with proper auth and email and hosting? That's the product.)

If You're About to Try This

A few practical things I learned that might save you time:

Start with the infrastructure, not the code. Set up your hosting, your auth provider, your email service, and your custom domains first. Get a "hello world" deployed to production before you write a single line of real application code. The number of problems that only surface in deployed environments is depressing.
Keep a credentials doc. You will have API keys, client IDs, callback URLs, database IDs, and secret keys scattered across 8 different dashboards. I use a local encrypted file. You can use 1Password or whatever. Just have a single place.
Budget twice as much time for "the last mile" as you think. If Claude helps you build the feature in 2 hours, budget another 2 hours minimum for deploying it, configuring the integrations, and testing in production.
Accept that some days will be all dashboard work. There were full days where I wrote essentially zero code but made critical progress: registering OAuth apps across three providers, setting up email, debugging DNS. Those days feel less productive but they're not.
Use multiple agents against each other. Don't just use one AI. Have Claude write the code, then point Codex or ChatGPT at it and ask what's wrong. Different models catch different things. It sounds redundant, but it's the closest thing to a code review you'll get as a solo developer.

Three weeks is still wildly fast for what I built. I'm not complaining about Claude. It let a single developer build something that would normally take a small team the better part of a year. But the story being told in the AI hype cycle (prompt, code, ship, done) is missing the entire middle section where you make it real.

The app is the easy part. Making it real is the job.

Stop Firing People Because AI Exists

2026-04-04T00:00:00Z

A friend of mine runs content for a mid-size SaaS company. Last year, her team was eight people. Writers, editors, a localisation specialist, someone who handled the knowledge base. Good team, solid output. Then the CEO attended a conference, came back fired up about AI, and within three months the team was down to three. The reasoning? "With AI tools, three people can produce what eight used to."

And technically, that's true. The three remaining people are producing roughly the same volume. Blog posts, help docs, product updates, internal comms. The numbers look fine on a dashboard.

But my friend hasn't slept properly in months. She's context-switching between writing, editing, prompt engineering, QA-ing AI output, managing translations, and doing all the strategic work that used to be shared across the team. Her two remaining colleagues are in the same boat. One of them is already looking for another job.

The company saved five salaries. It's also slowly losing the three people who actually know how things work.

The math that looks right but isn't

Here's the pitch that's been making the rounds in boardrooms since ChatGPT went mainstream: one person with AI can now do the work of ten. And if that's the case, why keep ten?

It's a compelling argument. Simple. Clean. Fits on a slide.

It's also dangerously incomplete.

Yes, AI can compress tasks. According to Microsoft's 2024 Work Trend Index, 90% of AI users at work say the tools help them save time. The heaviest Microsoft Teams users summarised eight hours of meetings using Copilot in a single month. That's a full workday reclaimed just from meeting summaries. And 85% say AI helps them focus on their most important work.

Those are real numbers. The productivity gains are not imaginary.

But here's what the "fire nine people" crowd never talks about: the person who remains doesn't just absorb the output. They absorb the cognitive load, the context, the decision-making, the coordination, the quality assurance, and every bit of institutional knowledge that walked out the door with those nine former colleagues.

Mental load is not a spreadsheet

There's a concept in psychology called cognitive load theory. It describes the total amount of mental effort being used in working memory at any given time. And every time you ask one person to do the thinking that five people used to share, you're not saving effort. You're concentrating it.

I think about this a lot when people tell me AI makes workers "10x more productive." Productive at what? Producing more words? Shipping more tickets? Generating more slide decks? Sure. But the actual hard part of knowledge work has never been the producing. It's the thinking. Deciding what to produce. Understanding context. Making judgment calls. Knowing when something is wrong even when it looks right on the surface.

AI doesn't do that for you. AI gives you a first draft, and now you need to be smart enough to evaluate it, experienced enough to catch the subtle errors, and present enough to notice when the output is confidently wrong. (If you've ever watched someone ship an AI-generated internal doc without reading it, you know exactly what I mean.)

Gallup's 2025 State of the Global Workplace report found that global employee engagement fell to 21% in 2024, down from 23% the year before. That drop cost the world economy an estimated $438 billion in lost productivity. Manager engagement dropped even harder, from 30% to 27%. Female managers saw a seven-point decline. Managers under 35 dropped five points.

These are the people who are supposed to be leading AI adoption. And they're burning out.

The amplification argument

Let me offer a different way to think about this.

If one person with AI can do the work of ten, then ten people with AI can do the work of a hundred.

Read that again. Because this is the part that almost nobody is talking about, and it's the part that should keep every CEO awake at night. Not because it's scary, but because it's an enormous opportunity that most companies are throwing away.

The companies laying off half their workforce because "AI can handle it" are not being efficient. They're being short-sighted. They're optimising for a quarterly headcount number while their competitors figure out what happens when you give powerful tools to a full team of motivated, experienced people.

I saw this play out at a startup event in Zurich last month. Two companies in the same space. Roughly the same size, same market. Company A had cut their content team from twelve to four. Company B had kept all twelve and given them AI tools plus training. Guess which one was producing multilingual content in six languages, running experiments with new formats, and shipping weekly product updates to their knowledge base? (It wasn't Company A.)

What actually happens when you cut

Let me walk through what happens in practice when you replace a team of ten with one or two "AI-enhanced" super-workers.

Week one feels great. The remaining people are energised. They have new tools. They're producing a lot. Leadership is thrilled. The dashboard numbers look incredible relative to headcount.

Month two, the cracks appear. The one person responsible for documentation discovers that AI-generated content needs serious review. Not light editing. Deep review. Because the AI doesn't know your product nuances, your customer context, or the three things you changed last week that invalidated half of what was written. The review work alone eats the time that was "saved" by generating content faster.

Month four, institutional knowledge gaps emerge. Remember those eight people you let go? They didn't just write content. They had relationships with product managers. They understood customer pain points from years of support ticket patterns. They knew which documentation topics generated the most questions. That knowledge is gone. The AI certainly doesn't have it.

Month six, you're hiring contractors. Because the remaining people are overwhelmed, quality has dropped, and someone finally noticed that the knowledge base hasn't been properly updated in weeks. But contractors don't have context either, so you're paying more per hour for worse results.

I'm not making this up. I've watched this pattern repeat at three different companies in the last year alone.

The data says keep your people (and train them)

The World Economic Forum's Future of Jobs Report 2025 asked over 1,000 global employers about their workforce plans. The numbers tell an interesting story. Yes, 40% of employers plan to reduce staff where AI automates tasks. But 85% plan to upskill their existing workforce. And 70% expect to hire people with new skills, not fewer people.

The report projects net job growth of 78 million by 2030. That's after accounting for the 92 million displaced roles. The world isn't moving toward fewer workers. It's moving toward differently skilled workers.

And here's the one that should give every "let's cut headcount" CEO pause: 64% of employers identified supporting employee health and well-being as a key strategy for talent availability. Not "reduce costs." Not "automate everything." Support well-being. Because companies that burn through their people don't get to hire the good ones later.

Meanwhile, a BCG and Harvard Business School study found that when teams used AI for creative tasks, around 90% improved their performance, with output quality rising 40% above control groups. But the study also found something that should make every leader uncomfortable: the diversity of ideas among AI-assisted groups dropped by 41%.

Think about what that means. You fire seven people from your ten-person team. The three who remain use AI to produce the same volume. But the range of ideas, perspectives, and approaches shrinks by nearly half. Your output looks productive but gradually becomes homogeneous. And nobody notices until a competitor ships something genuinely creative and you can't figure out why your team isn't doing the same.

The mental load nobody budgets for

Microsoft's survey found that 68% of people struggle with the pace and volume of work, and 46% feel burned out. And this was the state of affairs before you told them they're now doing the jobs of their three former teammates.

Here's something that doesn't show up in productivity dashboards: the cognitive cost of being the last line of defence. When you're the only person reviewing AI output, you don't get to have an off day. When you're the sole owner of the knowledge base, every support question lands on your desk. When there's nobody to bounce ideas off because the team was "right-sized," every decision is yours alone.

I've been building this platform partly because I've seen this problem up close. When documentation teams shrink, the knowledge doesn't shrink with them. The amount of content that needs to exist, stay current, and be accurate across languages doesn't decrease just because there are fewer people maintaining it. If anything, it grows (this is exactly the problem I'm building this to solve, by the way, with features like forced expiry dates and block-level translations that make smaller teams genuinely more effective rather than more overwhelmed).

But even the best tools don't fix a fundamentally broken staffing decision. You can't automate away the need for human judgment, context, and care. You can only make those humans more effective.

What smart companies actually do

The most impressive thing about the Microsoft data is what the "AI power users" look like. These are people who use AI multiple times a day and save over 30 minutes. They're 68% more likely to experiment with different ways of using AI. They don't just generate more output. They redesign how work happens.

And here's the kicker: they exist within organisations that invest in them. AI power users are 61% more likely to hear from their CEO about the importance of AI at work. They're 53% more likely to receive encouragement from leadership to rethink their entire function. They get tailored training, not just a ChatGPT login.

In other words, the most productive AI workers aren't lone survivors of a layoff. They're members of supported, invested-in teams.

Let me contrast that with what I see at companies that took the "cut headcount" route. Their remaining employees aren't power users. They're overwhelmed generalists desperately trying to keep things running. They don't have time to experiment with AI because they're too busy using it for survival. There's no rethinking the function because the function is just... them, alone, doing everything.

The knowledge problem nobody mentions

There's one more thing. And I don't hear anyone talking about it, which is odd because it should be obvious.

When you fire experienced knowledge workers, the knowledge leaves with them. It does not stay in the building. It's not in the wiki. It's not in the AI. It's in the heads of the people who built the processes, understood the edge cases, and knew which customers cared about which details.

You know what happens when you have great AI tools and no institutional knowledge? You get beautifully formatted, confidently delivered, completely wrong information. At scale.

I talked to a head of documentation at a fintech company last month (she didn't want to be named, which tells you something). After their team was cut from six to two, they started relying heavily on AI to maintain their developer docs. Within four months, they noticed a spike in support tickets. The docs looked fine. They were well-written, up to date on the surface. But they contained subtle errors that only someone with deep product knowledge would have caught. An API parameter description that was technically correct but practically misleading. A migration guide that missed a step everyone on the old team just knew about. Little things that AI can't know because AI doesn't attend your standups, doesn't read your Slack threads, doesn't hear the frustrated "oh, that doc is wrong again" from the support engineer at the coffee machine.

The real question

So here's what I think the conversation should actually be about.

Not: "How many people can we cut now that we have AI?"

But: "What becomes possible when we give AI to everyone we already have?"

Your ten-person documentation team with AI tools doesn't become redundant. It becomes a team that can maintain content in twelve languages instead of two. That can keep every piece of content current with automated freshness checks. That can experiment with new formats, run A/B tests on help content, build interactive guides, and still have time to think strategically about what customers actually need.

Your ten-person marketing team with AI doesn't become five people doing the same work with more stress. It becomes ten people who can personalise campaigns at a scale that was previously impossible, test more creative variations, respond faster to market changes, and still have the cognitive bandwidth to come up with genuinely original ideas that the AI never would have generated.

That's not a cost. That's an investment with a return that compounds.

Where this ends up

The companies that win the next five years won't be the ones who cut the most heads. They'll be the ones who figured out how to make their existing teams genuinely more capable.

The question isn't whether one person can do the work of ten. The question is what happens when all ten can do the work of a hundred.

If you're a leader reading this, I'd ask you one thing. Before you approve that next round of "AI-enabled restructuring," talk to the people who stayed after the last one. Ask them how they're doing. Ask them what they've stopped doing because there's no time. Ask them what's falling through the cracks.

And then imagine what they could accomplish if, instead of carrying the load alone, they had a full team and the best tools available.

That's not a fantasy. For the companies willing to invest in their people instead of replacing them, that's the next twelve months.

Readers and Writers Are in Different Mental Modes. Why Does Every Tool Give Them the Same UI?

2026-04-03T00:00:00Z

Open Confluence right now and find a document you need to read. What do you see?

A toolbar. Edit buttons. Comment boxes. Page history links. A sidebar full of navigation you don't need. Breadcrumbs. Metadata fields. Permission indicators. An entire authoring interface wrapped around the text you came here to read.

Now think about what you actually wanted: the answer to a question, or the next three steps in a process, or a policy you need to reference before a meeting in ten minutes.

You came to consume. The interface assumed you came to create.

This is the default in almost every documentation platform. Confluence, Notion, SharePoint, GitBook, Nuclino, Slite. They all present the same environment to readers and writers. The page is the page. Everyone gets the same view, give or take a few permission-gated buttons.

It feels normal because we've never had anything else. But it's a design decision, not a law of nature. And it's the wrong one.

Reading and writing are not the same cognitive task

This isn't a UI preference. It's a fundamental difference in how the brain works.

When you write, you're in generative mode. You're constructing, organising, deciding what to include and what to leave out. You need tools: formatting options, structure controls, media embedding, metadata fields, version history, collaboration features. The interface should give you power and flexibility.

When you read, you're in receptive mode. You're scanning, filtering, extracting what's relevant, and trying to move on. You need clarity: clean typography, focused layout, minimal distraction. The interface should get out of the way.

Cognitive psychology has a clear framework for this. Cognitive Load Theory, developed by John Sweller in the late 1980s, distinguishes between intrinsic load (the difficulty of the material itself), germane load (the effort of learning and integrating), and extraneous load (everything the environment adds that doesn't help). Every toolbar, sidebar, and edit button visible to a reader is extraneous load. It doesn't help them understand the content. It actively competes for attention.

Research by Mayer and Moreno (2003) on multimedia learning demonstrated that reducing extraneous elements improves both comprehension and retention. Their coherence principle is direct: people learn better when extraneous material is excluded rather than included. A documentation interface that shows authoring controls to readers is violating this principle on every single page load.

The reader doesn't need to see the writer's tools. Showing them anyway isn't neutral. It's actively harmful to comprehension.

How current platforms handle this (they mostly don't)

Let's look at what exists.

Confluence has a read mode and an edit mode, but the read mode is still surrounded by the platform's navigation, metadata, and page tree. The editing toolbar disappears when you're not editing, but the mental frame of "this is an editable wiki page" never fully goes away. Every reader sees the "Edit" button. The page whispers: you could change this.

Notion is worse in this regard. Its core design philosophy is that everything is always editable. Click anywhere and you're typing. That's brilliant for writers. It's terrible for readers who just want to absorb content without the anxiety of accidentally modifying something. Notion's own template gallery shows this: every template is a workspace, not a publication.

SharePoint technically supports different page layouts for viewing and editing, but the overall experience is still corporate intranet. Readers feel like they're inside an enterprise tool, not reading a document optimised for understanding.

GitBook comes closest to a reading-first experience, with its clean documentation-style output. But even there, the reader experience serves the assumption that the reader is a developer looking at technical docs. It's not designed for the general knowledge consumer.

None of these platforms treat reading as a fundamentally different activity from writing. They treat it as writing with the toolbar hidden.

The cost of a single interface

This isn't just an aesthetics problem. It has measurable consequences.

Information overload reduces comprehension

A study published in the Journal of Consumer Research found that information overload leads to poorer decision quality, with the effect increasing as the ratio of irrelevant to relevant information grows. A documentation page with visible authoring controls, navigation trees, and metadata fields increases that ratio for every reader who isn't there to write.

Context switching has a real cost

When an interface signal says "you can edit this," it activates a different cognitive frame than "read this." Gloria Mark's research at UC Irvine on attention and multitasking found that it takes an average of 23 minutes and 15 seconds to fully refocus after a context switch. A reader who momentarily considers editing (even to fix a typo) has been pulled out of reading mode. That's not a hypothetical. Anyone who has used Notion knows the experience of clicking to select text and accidentally starting to type.

Readers and writers have different needs from the same content

A writer needs to see structure, formatting markers, block types, metadata, and collaboration signals. They need the full machinery.

A reader needs to see clean text, clear hierarchy, and the fastest path to the information they're looking for. They need the content, not the machinery.

Serving both from the same interface means neither gets an experience optimised for what they're actually doing.

And then there's the third audience: AI

This is where it gets complicated, and where existing platforms are completely unprepared.

Documentation in 2026 has three distinct consumers, not two:

Writers who create and maintain content
Readers who consume content visually
AI systems that retrieve, parse, and synthesise content programmatically

Each of these audiences needs a fundamentally different interface to the same underlying content.

Writers need rich editing tools, collaboration features, and structural controls. Readers need clean, focused presentation with minimal distraction. AI needs structured, machine-parseable output with explicit metadata: freshness signals, classification labels, block-level addressing, and clean semantic markup.

As we discussed in Builders, Not Developers, AI intermediaries are already the dominant consumer of documentation for a growing share of knowledge workers. GitHub's 2024 developer survey found 97% of enterprise developers have used AI coding tools. By 2026, 84% of developers use AI tools regularly, with 41% of all code being AI-generated.

These AI systems don't care about your sidebar or your toolbar. They need clean data. And a platform that conflates the reader view with the writer view is also conflating the AI-consumable surface with the human authoring surface. That's three mismatches in one interface.

How this approach separates the experiences

this platform is built around the principle that creating content and consuming content are different activities that deserve different interfaces.

The writer's environment

When you're writing in this platform, you get a full authoring environment. Rich text editing with TipTap, block-level controls, translation status indicators, expiry management, collaboration tools, content structure views, and everything else a writer needs to create and maintain high-quality documentation.

The writer sees the machinery because they need the machinery.

The reader's environment

When someone consumes a this platform document, they see a clean, focused reading experience. No editing chrome. No toolbars. No "you could modify this" signals. Just the content, presented in a layout optimised for comprehension and scanning.

The reader doesn't see the edit button because they're not here to edit. They're here to learn something, follow a process, or find an answer. The interface respects that intent.

The AI surface

For AI consumers, this platform exposes content through structured APIs with full metadata. Every block carries its freshness score, translation status, content hash, and classification labels. AI systems can query content at the block level, filter by freshness, exclude stale or draft material, and retrieve exactly the structured data they need.

No scraping a wiki page and hoping for the best. The AI gets a purpose-built interface, just like the reader and the writer do.

One content layer, three interfaces

The important thing is that we're not maintaining three copies of the content. This isn't the five-copies-of-onboarding problem we discussed in Stop Maintaining Five Copies of the Same Document.

It's one content layer, stored as structured blocks, served through three different views optimised for three different audiences.

The writer edits blocks. The reader sees assembled, styled content. The AI queries structured data with metadata. Same blocks. Same source of truth. Different presentation layer for each consumer.

This is only possible because of the block-level architecture. Each piece of content is an individually addressable unit with its own metadata. You can present those blocks differently depending on who's asking for them:

Audience	Needs	Gets
Writer	Formatting, structure, collaboration, metadata	Full authoring environment with block-level controls
Reader	Clean text, clear hierarchy, fast scanning	Focused reading view, no editing chrome
AI	Structured data, freshness scores, classification	Block-level API with full metadata

Why this matters more than it looks

You might read this and think: "It's just UI. Different views of the same thing. How important can it be?"

Very important, it turns out.

Reader trust

People trust content that looks published. When a page looks like a wiki that anyone can edit, readers unconsciously discount it. When the same content is presented in a clean, publication-quality reading view, it carries more authority. This isn't irrational. It's a signal that someone took the presentation seriously, which implies they took the content seriously too.

Nielsen Norman Group has studied this extensively. Their research on content credibility shows that design quality and presentation are among the strongest signals users rely on to assess content trustworthiness. A cluttered editor view actively undermines the credibility of the content it displays.

Writer productivity

Writers who work in a dedicated authoring environment don't have to context-switch between "am I reading or am I writing?" The tools are there because they're supposed to be there, not because the interface couldn't decide who was looking at it.

AI reliability

When AI systems have a purpose-built surface with structured metadata, they can make better decisions about what to retrieve and what to exclude. They can check freshness scores before including a block in an answer. They can respect classification labels. They can filter by language, status, or audience. None of that is possible when the AI is scraping the same HTML page that was designed for human readers.

The mental model shift

The fundamental assumption of most documentation platforms is: the page is the unit, and everyone interacts with the page.

this platform's assumption is different: the block is the unit, and different audiences interact with blocks through purpose-built surfaces.

That sounds like a small architectural distinction. It's not. It's the difference between a tool that accidentally shows content to AI systems and one that deliberately serves them. Between a writing environment that happens to be readable and a reading experience that was designed from scratch. Between one good-enough interface and three great ones.

Documentation is no longer just written and read. It's written, read, queried, translated, scored, classified, and served to AI systems at scale. A single interface can't optimise for all of that, and pretending it can is how we ended up with wikis that nobody wants to read and AI assistants pulling answers from pages that were never designed to be machine-consumed.

Readers and writers are in different mental modes. AI is in a different mode entirely. The interface should reflect that.

The State of Docs in 2026: Five Trends That Will Define the Next Era

2026-04-03T00:00:00Z

Every few months I block out a morning to just read. Not this platform code, not GitHub issues. Competitor blogs, industry reports, keynote announcements, developer surveys. Whatever shipped in the last quarter that touches documentation, knowledge management, or AI-assisted workflows.

I did that last week, and the picture that emerged was sharper than I expected. Not because any single announcement was groundbreaking, but because five separate trends are converging, and when you line them up, they paint a very clear picture of what documentation platforms will need to do in the next two years.

Here's what I found.

1. AI is the primary reader now. Not humans.

GitBook published a striking number in their AI docs data report: AI readership of documentation increased over 500% in 2025. Five hundred percent. That's not a rounding error.

Meanwhile, Stack Overflow's 2024 Developer Survey showed that 61% of developers spend more than 30 minutes a day searching for answers. But how they search has shifted. GitHub's own survey found 97% of enterprise developers have used AI coding tools. By 2026, 84% of developers use AI tools daily, with 41% of code now AI-generated. These people aren't navigating your wiki sidebar. They're asking Claude or Copilot, and the AI is reading your docs on their behalf.

The implication is hard to overstate. Your most frequent documentation consumer is no longer a person with a browser tab open. It's a language model making retrieval calls. And that model has no ability to squint at a page and think "hmm, this looks outdated."

GitBook spotted this early and responded with their State of Docs 2026 report and a push toward machine-readable formats. They also shipped skill.md, a convention for structuring product information specifically for AI agents. Google went further with their Gemini API Docs MCP, which connects coding agents to current documentation via the Model Context Protocol. Their reasoning was explicit: agents generate outdated code because their training data has a cutoff date. The MCP fix brought their eval pass rate to 96.3%.

So the first trend is settled. AI is the primary reader. The platforms that treat this as a core design constraint, not a feature to add later, will have a structural advantage.

2. Freshness and trust metadata are becoming mandatory

Anthropic interviewed 81,000 Claude users in December 2025 and published the results in March 2026. It's the largest qualitative study of AI users ever conducted (159 countries, 70 languages). The single most-cited concern? Unreliability. 27% of respondents named it as their top worry, and 79% of those people had experienced it firsthand.

That number should keep every documentation team up at night.

When AI answers are unreliable, the problem isn't always the model. Often the model is faithfully reproducing what it found in a stale document. The model didn't hallucinate. Your docs were just wrong, and nobody flagged them.

Stack Overflow's data reinforces this from a different angle: 81% of developers expect AI to be more integrated in how they document code in the coming year. If 81% of your users are feeding docs to AI, and 27% of AI users say unreliability is the biggest issue, you have a trust problem that no amount of prompt engineering fixes. The fix is at the source.

This is why freshness metadata matters. Not "last edited" timestamps (those tell you when someone touched the file, not whether the content is still accurate). Real freshness: review status, link health, translation alignment, readership signals, content drift detection. Metadata that a machine can read and use to decide whether a document is safe to cite.

I keep coming back to a simple framing. Your documentation needs a credit score. Not a timestamp. A credit score. (We've been building exactly this with this platform's freshness scoring system, and honestly, seeing the industry data only makes me more convinced it's the right call.)

3. Translation is moving from "project" to "pipeline"

DeepL published a piece in February called "The 6 Translation Transformations Global Businesses Can't Afford to Miss". Their argument: translation is becoming a continuous operating challenge, not a batch project you do quarterly.

That tracks with everything I see.

The old model was straightforward. Write in English. When you have budget, hire a translator or run it through a service. Get the translations back. Upload them. Done until next time. The problem is that "next time" comes faster and faster when your product ships weekly and your docs update constantly. By the time the German version is back from review, the English source has already changed twice.

DeepL's own Customization Hub now offers glossaries, style rules, and formality settings, which is great. But if those tools live outside your documentation platform, you're managing a translation toolchain: editor, export, translate, review, reimport, repeat. Every step is a chance for drift.

Notion has no native multilingual support at all. Confluence offers it through marketplace plugins. GitBook added auto-translate in August 2025, which is a step, but it operates at the page level.

The real shift is from page-level to block-level. When you track translations at the paragraph level, you only retranslate what actually changed. A typical edit touches maybe two paragraphs out of forty. That's 94% less translation work. (This is this platform's core translation architecture and, honestly, the thing I'm most proud of in the product. But even setting us aside, the industry direction is clear: continuous, incremental, embedded translation is where this is heading.)

4. AI agents need structured content, not wiki pages

This one crystallised for me when Notion announced Custom Agents in February. 21,000 agents built during early access. Agents that answer questions from knowledge bases, route tasks, compile status reports. Ramp alone has over 300 agents.

Atlassian went in a similar direction. Rovo AI in Confluence pulls context from across Atlassian and third-party apps to generate content. Their pitch: "context-rich, high-quality content grounded in your team's existing work."

And then Anthropic shipped agent teams in Claude Code, where multiple AI agents coordinate autonomously on complex tasks. Opus 4.6 scores 76% on the 8-needle 1M MRCR benchmark (up from 18.5% for the previous model), meaning it can actually retrieve information buried deep in massive document sets without losing track.

All three companies are building agents that consume documentation. None of them have solved the quality-of-source problem.

Notion's Custom Agents documentation explicitly acknowledges the prompt injection risk when agents read untrusted content. Atlassian's Rovo grabs whatever it finds in your Confluence. If that content is three months stale, Rovo doesn't know. It builds on it anyway.

For agents to work reliably, they need more than pages of text. They need structured content with stable identifiers, explicit freshness signals, clear classification metadata, and the ability to distinguish "this is current and reviewed" from "this exists but nobody's touched it in a year." Wiki pages don't provide that. Structured block-level content with trust metadata does.

5. Open source and self-hosting are making a comeback

This last one is more of a gut feeling backed by data than a single announcement.

GitBook open-sourced their published documentation in late 2024 and launched an OSS fund. Their reasoning: open source projects deserve free, high-quality documentation tooling. But the move also signals something broader.

Notion is cloud-only. No self-hosted option. Confluence Data Center exists but requires a license. When your documentation platform holds your most sensitive operational knowledge (incident playbooks, compliance procedures, architecture decisions), the question of "who controls this data?" is not abstract.

Anthropic's "Claude is a space to think" post from February made an interesting argument about trust and business models. Their core claim: advertising incentives are incompatible with a genuinely helpful AI assistant. They chose to stay ad-free so users can trust the tool.

I think there's a parallel for documentation platforms. If your docs system is closed-source and cloud-only, you can't verify what it feeds to AI. You can't audit the freshness calculations. You can't ensure your data stays in your control. For teams that are deploying AI assistants on top of their knowledge base (and increasingly, everyone is doing this), auditability matters.

This is not a polemic about open source being morally superior. Closed-source products can absolutely be trustworthy. But when you're building AI-powered workflows on top of your internal documentation, the ability to inspect and verify the system is a practical advantage. For us, MIT licensing this platform wasn't an afterthought. It was a design decision rooted in the same logic: documentation infrastructure should be auditable.

What these five trends mean together

Individually, each of these trends is manageable. AI reads your docs? Okay, add some machine-readable metadata. Freshness matters? Fine, add review dates. Translation needs to be continuous? Sure, integrate DeepL. Agents need structure? Fair, improve your content model. Sovereignty matters? Great, offer a self-hosted option.

But taken together, they describe a platform that looks fundamentally different from what most teams are using today.

The gap is architectural. These aren't five features you bolt on. They're five assumptions that need to be baked into the foundation. How content is stored (block-level, not page-level). How trust is modelled (freshness scores, not timestamps). How translation works (incremental, embedded, per-paragraph). How AI agents access content (structured APIs with metadata, not page scrapes). How data is controlled (open, auditable, self-hostable).

No established platform was designed around all five of these simultaneously. Some are adding them piece by piece. GitBook is moving fastest on the AI readability front. Notion is building agent infrastructure. Atlassian has enterprise distribution.

But designing for all five from day one? That's the advantage of starting fresh when the ground shifts.

I realise I'm biased here. I built this specifically because we saw these trends converging and wanted a platform that assumed all of them from the start. Block-level translation, forced expiry, freshness scoring, structured AI-ready content, open source. It's the thesis of the whole project.

But even if we didn't exist, I think any honest reading of what happened in the first quarter of 2026 points in the same direction. Documentation is becoming infrastructure. And infrastructure has different requirements than wiki pages.

The teams that figure this out first won't just have better docs. They'll have more reliable AI agents, lower translation costs, fewer compliance surprises, and knowledge bases that actually stay trustworthy over time.

That's the state of docs in 2026. The question isn't whether these trends are real. It's whether your platform was designed for them.

Five trends. One architectural question: was your documentation platform designed for 2026, or is it still serving assumptions from 2016?

Sources: GitBook AI docs data report, GitBook State of Docs 2026, GitBook skill.md, Google Gemini API Docs MCP, Stack Overflow 2024 Developer Survey, GitHub 2024 developer survey, Index.dev developer productivity statistics, Anthropic "What 81,000 People Want from AI", Anthropic "Claude is a space to think", Claude Opus 4.6, Notion Custom Agents, Atlassian Rovo in Confluence, DeepL "6 Translation Transformations", DeepL Customization Hub, GitBook open source documentation, GitBook auto-translate.

Builders, Not Developers: How Claude Changed Who Your Docs Are For

2026-04-02T00:00:00Z

There is a person right now, somewhere, integrating your API. They're not on your documentation site. They haven't opened your getting-started guide. They have never seen your interactive playground or your carefully designed sidebar navigation.

They're sitting in Claude. Or Copilot. Or Cursor. They typed something like "integrate the Stripe billing API with my Next.js app using the app router" and waited for working code to come back. The AI read your docs on their behalf. It found the relevant endpoints, understood the authentication flow, picked the right SDK methods, and produced an implementation.

Two weeks ago at Start Summit Hackathon in St. Gallen, I watched this happen in real time. I was talking with a group of CS students and a couple of early-stage startup founders about how they approach new APIs, and every single one of them described the same workflow: paste the problem into an AI, get code back, iterate from there. One of the students laughed when I asked if she'd read the docs. "Why would I? Claude reads them for me."

The person never visited your site. They may never visit your site. And this is increasingly just how software gets built.

The core shift

Documentation now has two fundamentally different consumers: humans who read it and AI assistants that read it on behalf of builders. Most documentation is optimised exclusively for humans. The AI is already the dominant reader.

This changes everything downstream:

Freshness is now a reliability issue. When an AI serves stale content, the builder has no way to detect the problem. The damage scales silently.
"Developer" is too narrow a word. Product managers, designers, and analysts are shipping software through AI assistants, often without ever reading a line of documentation themselves.
Machine-readable structure matters more than visual design. Clean markdown, self-contained blocks, and explicit metadata are what allow AI to represent your product accurately.
Format requirements have split. Human readers need narrative. AI intermediaries need structured, parseable specs. You need to serve both.

The rest of this post unpacks how we got here, what this means for DevRel, and what you can do about it right now.

The journey nobody planned for

For a long time, developer relations followed a well-understood path. You wrote comprehensive documentation. You published quickstart guides. You gave conference talks. You maintained a presence on Stack Overflow. You made your API reference searchable, your SDKs idiomatic, your error messages helpful.

That path assumed the developer would read your content. Navigate your structure. Follow your steps.

GitHub's 2024 developer survey found that 97% of enterprise developers have used AI coding tools at some point. Stack Overflow's annual survey showed 76% of all developers are using or planning to use AI tools, with 62% of professionals actively using them day to day. By 2026, that number climbed to 84%, with 41% of all code now AI-generated and 51% of professional developers using AI tools daily. Those numbers aren't slowing down.

The new journey looks different. Someone describes what they want in natural language. An AI assistant reads the documentation, finds the relevant sections, and generates the integration. The builder reviews the output, maybe refines the prompt, maybe asks a follow-up. Minutes, not hours.

The getting-started funnel that DevRel teams spent years perfecting? It's being bypassed. Not because it was bad. The entry point just moved.

Two consumers, one set of docs

Documentation now has two fundamentally different audiences.

The first is the human reader. This person still exists. They show up for architecture decisions, edge case debugging, compliance review, and conceptual understanding. They want narrative explanations, well-organised reference material, and clear reasoning about trade-offs.

The second is the AI intermediary. It reads your documentation on behalf of a builder. It does not care about your sidebar. It does not appreciate your visual design. It needs structured, machine-parseable content: clean markdown, consistent formatting, explicit specifications it can reason about without ambiguity.

Almost every documentation site today is optimised exclusively for the first audience. The second audience is already the dominant consumer.

Jeremy Howard identified this tension when he proposed the /llms.txt standard in 2024. His observation was precise: "Large language models increasingly rely on website information, but face a critical limitation: context windows are too small to handle most websites in their entirety." The proposal is simple. A curated markdown file at /llms.txt that gives AI models a structured overview of your product and links to the most important resources. FastHTML, Anthropic's own docs, and a growing directory of projects now ship one.

It is a useful convention. But it is also a symptom of a deeper problem. The real issue is not format. It is that most documentation was never designed with machine consumption in mind.

The builder is not cutting corners

There's a temptation to look at the person who prompts Claude instead of reading docs and conclude they're taking shortcuts. That they don't really understand what's happening in the code. That they're somehow a lesser kind of developer.

I've had this conversation enough times now to know that's usually wrong.

Many of these builders are senior engineers making deliberate efficiency choices. They understand the code, they just don't want to navigate four pages of documentation to find the three lines they actually need. They've learned that an AI assistant can extract those lines faster than they can scan for them, so they delegate the reading. (Honestly, I do this myself. I can't remember the last time I read a getting-started guide top to bottom.)

Anthropic recognised this pattern when they built the Model Context Protocol. MCP is now supported by Claude, ChatGPT, VS Code, Cursor, and others. It's explicitly designed so AI assistants can reach into external systems, pull context, and act on it. The specification describes it as providing "access to an ecosystem of data sources, tools and apps which will enhance capabilities and improve the end-user experience."

Read that carefully. It's infrastructure language, not convenience language. The builders using these tools aren't avoiding work. They're working through a new layer, and your documentation is part of that layer whether you designed it to be or not.

The numbers back this up. Claude alone now handles 25 billion API calls per month, with 30 million monthly active users across 159 countries. 70% of Fortune 100 companies use Claude. According to a Menlo Ventures survey, Anthropic holds 32% of enterprise AI market share by model usage, ahead of OpenAI at 25%. An HSBC research report puts that even higher: 40% by total AI spending. These aren't experimental tools. They're primary infrastructure.

Developer relations was built for a different era

If your DevRel strategy was designed before 2023, it was designed for a world where developers read docs directly. That world hasn't disappeared, but it's no longer the dominant interaction pattern for a growing share of builders.

This changes the calculus on several long-standing DevRel activities.

Conference talks. A 45-minute presentation at a developer conference reaches a room of a few hundred people. A well-structured /llms.txt file and clean machine-readable documentation reach every builder who asks any AI assistant about your product, continuously, at any time. The talk is a one-time event. The machine-readable docs compound. I'm not saying conferences are worthless (I literally just came back from one), but the leverage equation has shifted.

Getting-started guides. The classic five-step quickstart tutorial is increasingly a formality. The builder doesn't follow steps. They describe what they want and expect the AI to produce the integration. If the API is well-documented in a machine-friendly format, the AI handles the getting-started experience more efficiently than any tutorial could. What tutorials should become instead is conceptual material: explaining why you'd choose approach A over approach B. The AI can generate the implementation. It's much less reliable at explaining the trade-offs.

Stack Overflow. Their own survey data showed that 84% of developers use technical documentation directly, with 90% of those relying on docs within API and SDK packages. But the way they access those docs is increasingly through an AI layer, not a browser tab. The questions that still reach Stack Overflow tend to be the hard ones. Edge cases, production debugging, things that require nuance. Valuable, sure. But no longer where the volume is.

When the AI reads your docs, freshness becomes critical

Here is the part that most teams have not thought through.

When a human reads a documentation page, they can apply judgement. They might notice the screenshots look old, or that a comment at the bottom says the process changed. They can squint at it and think "this feels outdated."

An AI assistant can't do any of that. It reads the text, processes it as fact, and generates an answer with full confidence. If the documentation describes a deprecated endpoint, the AI will cheerfully recommend integrating with it. If the documentation references infrastructure that was replaced six months ago, the AI will describe the old setup as current. No hesitation.

And here's the thing that makes this worse than it sounds: 66% of developers already say the biggest problem with AI tools is that they give results that are "almost right but not quite." Stale documentation feeds directly into that problem. The AI isn't hallucinating. It's faithfully reproducing outdated content, and there's no way for the builder to tell the difference.

The builder trusts the AI. The AI trusts the documentation. If the documentation is stale, that trust chain delivers a confidently wrong answer.

This was always a problem, obviously. Stale content has always confused people. But the damage was contained because human readers could sometimes catch it. AI intermediaries can't. They amplify stale content by serving it at scale, with authority, to people who have no reason to doubt it.

Freshness isn't a content quality issue anymore. It's a reliability issue for every AI-powered workflow that touches your docs.

The word "developer" is too narrow

The people building software in 2026 don't all identify as developers. Some are designers who prompt Claude to build a working prototype. Some are product managers who use Cursor to ship internal tools. Some are data analysts who describe a data pipeline in natural language and let an agent assemble it. At Start Summit, half the hackathon teams had members with zero programming background who were shipping working software by the end of the weekend.

Ramp is a useful example. The fintech company went from a $5.8B valuation in 2023 to $32B by late 2025, crossing $1B in annualised revenue along the way. One of the fastest-growing startups in history. A widely discussed part of their approach: product managers building features directly with AI tools instead of waiting in an engineering backlog. PMs at Ramp do not just write specs. They ship code. The AI handles the implementation. The PM handles the intent.

Not a shortcut. A new operating model, and it's working at a scale that makes it really hard to dismiss as an experiment.

Anthropic's own internal study is revealing here. When they surveyed 132 of their own engineers about how they use Claude, the engineers reported using it for about 60% of their work tasks. The most common uses? Debugging existing code, understanding what parts of the codebase were doing, and implementing new features. The engineers said they tend to hand Claude tasks that are "not complex, repetitive, where code quality isn't critical." And 27% of the work they now do with Claude simply wouldn't have been done at all before.

That's Anthropic's own team. The people who built the model are using it as a documentation reader, a codebase navigator, and a first-draft generator. Everyone else is doing the same, just with your docs instead of theirs.

Anthropic has been deliberate about calling this the "builder" persona. Their tools are designed not just for professional software engineers but for anyone who can describe what they want to build. When Claude can scaffold a full-stack application from a Figma design via MCP, the traditional line between "developer" and "non-developer" dissolves.

This has real implications for anyone who maintains documentation or cares about developer experience. Your audience is no longer limited to people who know what a REST endpoint is. It includes anyone whose AI assistant might interact with your product. The PM at Ramp who ships a feature using your API? Probably never reading your documentation directly. Their AI agent absolutely will.

What this means for documentation

If documentation now serves two audiences, human readers and AI intermediaries, it needs to work for both. Sounds obvious. In practice, almost nobody does it.

Here's what I think actually matters:

Machine-readable formats alongside human-readable ones. If your API docs are a beautifully rendered HTML page that an LLM has to scrape and parse, the AI is working harder than it should. Ship the raw OpenAPI spec alongside the rendered version. Ship clean markdown. Make the specifications accessible without requiring the AI to interpret page layout.

Block-level structure instead of page-level narrative. AI assistants do not consume documentation page by page. They extract relevant sections. A document with clear headings, self-contained paragraphs, and explicit block-level semantics is dramatically more useful to an AI than a flowing narrative that requires reading the entire page for context.

Trust signals that machines can read. When was this document last reviewed? Is this still current? Has the content been flagged? These signals need to exist in a form the AI can access, not just as visual cues on a web page. A freshness score, an expiry status, a review date, these are the metadata that allow an AI to decide whether a document is safe to use as a source.

Freshness as a prerequisite, not a feature. When an AI assistant serves a builder a confident answer based on a deprecated endpoint, the damage is worse than a 404. The builder builds on it. Ships it. Then it breaks in production, and nobody knows why until someone traces it back to documentation that should have been updated months ago. Every document that an AI might reference needs a mechanism to prove it's still current. (This is, full disclosure, exactly the problem I'm building this to solve. Forced expiry on documentation blocks so stale content can't hide.)

Getting started: audit your current docs

If you've read this far and you're thinking "okay, but what do I actually do on Monday," here are four concrete things you can check this week.

1. Test your docs through an AI. Open Claude or ChatGPT and ask it to integrate your product in a realistic scenario. Don't use your internal knowledge. Just look at what the AI produces. Is it correct? Is it current? Is it using the right endpoints, the right SDK version, the right auth flow? If the AI gets it wrong, that's what builders are getting right now.

2. Check for stale content. Pick your five most-visited documentation pages and ask: when was this last reviewed? Does it still describe the current state of the product? If you can't answer that confidently, neither can an AI. This is the single highest-leverage fix for most teams.

3. Ship machine-readable formats. If you don't have a /llms.txt file, create one. If your API reference is only available as rendered HTML, export the raw OpenAPI spec and make it accessible. If your docs are in a CMS that doesn't output clean markdown, that's a problem worth solving now.

4. Add review dates and freshness metadata. Even something simple, a last-reviewed field in your content management system, a mandatory review cycle for high-traffic pages. This gives both humans and AI a signal about whether content is trustworthy. Tools like this platform can automate this with forced expiry at the block level, but even a manual process is better than nothing.

The quiet shift in how products are represented

There is a broader consequence of all this that is worth stating directly.

Your documentation is no longer just a reference manual for developers. It's the source material that AI assistants use to represent your product to the world. When a builder asks Claude how to use your product, Claude's answer is shaped by whatever it can find and parse from your docs.

Good docs, good answer. Outdated, ambiguous, locked inside HTML that's hard for a model to parse? Worse answer, or an incorrect one. Simple as that.

The quality of the AI's answer about your product is now a direct proxy for your developer experience. Most companies aren't treating it that way yet.

The teams that are ahead on this, Stripe, Vercel, Cloudflare, Anthropic themselves, treat AI readability as a first-class concern. A foundational requirement that shapes how documentation gets written, structured, and maintained. Not a backlog item for next quarter.

The builder sitting in Claude right now, describing what they want to build, expecting working code in minutes. They may never visit a documentation site again. But the AI that serves them will. Constantly.

That AI is now your most frequent reader. The question is whether your docs are ready for it.

The best developer experience strategy in 2026 is not a conference talk or a quickstart guide. It is making sure the AI gets it right.

This post references publicly available research and product documentation. Statistics are drawn from GitHub's 2024 developer survey, the Stack Overflow 2024 Developer Survey, Index.dev's 2026 developer productivity report, Incremys Claude statistics, and Fortune's reporting on Anthropic. The /llms.txt specification is maintained at llmstxt.org. The Model Context Protocol is documented at modelcontextprotocol.io.

How This Translation Approach Actually Works, And Why It Sounds Like Your Team

2026-03-31T00:00:00Z

If you've ever run a document through Google Translate, or honestly any translation tool, you know the result. Technically correct. Tonally wrong. Your product is suddenly called something different. Your team's internal shorthand disappears. Formal "you" where your company uses informal, or the other way around.

The output is translated, but it doesn't sound like you.

That's what I built this platform's translation system to fix. Not "can we translate documentation" (every tool can do that now) but "can we translate it so it actually sounds like our team wrote it."

The answer is yes. And it doesn't require a team of professional translators to get there.

Only what changed gets translated

Most documentation platforms translate entire pages. You change one sentence and the whole document goes off for retranslation. Every language, every paragraph, whether it changed or not.

this platform works differently. It tracks every paragraph individually. When you edit one section of a 20-section document, only that one section gets retranslated. The other 19, across all languages, stay exactly as they were.

This means two things:

Your translation costs drop dramatically. We're talking 94% less for typical edits. Most updates touch one or two sections, not the whole page.
Translations you already reviewed stay stable. If your German team approved a translation last week, editing an unrelated paragraph in English won't touch their approved text.

The system knows what changed because every paragraph has a unique identity and a content fingerprint. When the fingerprint changes, that specific paragraph is flagged for retranslation. Nothing else.

Your glossary, your terminology

Here's where it gets interesting.

Every company has its own vocabulary. "Sprint Review" might stay as "Sprint Review" in your German docs because your Berlin team uses the English term. Or it might become "Sprint-Überprüfung" because your Munich team prefers the German version. "Knowledge Base" might be "Wissensdatenbank" or "Knowledge Base" or something entirely different your team coined internally.

this platform lets you build a glossary for each language. Basically a list of terms and their approved translations. When a paragraph is translated, the system checks your glossary first. Every term in your list gets translated exactly the way you defined it. Every time. Across every document.

You can manage your glossary directly in this platform:

Add terms one by one as you notice inconsistencies
Import a CSV if you already have a terminology list from another system
Export your glossary to share with external translators or other tools

The glossary works per language pair. Your English-to-German glossary is separate from your English-to-French glossary. This matters because the same English term might need different treatment in different languages. "Sprint Review" might stay English in German but get translated in Japanese.

When you update your glossary, the change takes effect the next time any paragraph is translated into that language. No need to retranslate everything manually. The next natural edit cycle picks it up.

Style rules: making translations sound like you wrote them

Glossaries handle individual words. But a translation can use all the right terms and still feel off. Wrong tone. Dates in the wrong format. Numbers with the wrong separator. Currency symbols in the wrong place.

That's what style rules are for.

For each language, you can set up a collection of rules that control how translations are shaped:

Formatting conventions

These are the details that make a document feel native rather than "obviously translated from English":

Date and time formats. 24-hour clock for German, AM/PM for English, and more
Number formatting. Comma as decimal separator in German (3,14 instead of 3.14), period for thousands
Punctuation rules. Academic degree formatting, quotation mark styles, and other regional conventions

You pick the conventions that match your company's standards. this platform applies them to every translation in that language, across every document.

Custom instructions

This is where things get really powerful. Custom instructions are plain-language directives that tell the translation engine how to handle your content. You write them in normal sentences, and the engine follows them.

Some examples:

"Use a friendly, diplomatic tone" for a company that wants approachable documentation
"Always use the formal 'Sie' form, never 'du'" for professional German communication
"Use British English spelling: colour, organisation, licence" when your English-speaking audience is UK-based
"Put currency symbols after the numeric amount" to match European conventions
"When describing API endpoints, use imperative mood" for technical docs that should feel direct

You can add up to 200 custom instructions per language. They work alongside your glossary and formatting rules, and the translation engine considers all of them together on every translation.

Formality

German has "du" and "Sie." French has "tu" and "vous." Japanese has multiple levels of politeness. Even languages without obvious formal/informal pronouns have tonal differences that matter.

this platform lets you set the formality level for each language. Once configured, every translated paragraph matches that tone. If your company addresses readers formally in French ("vous") but informally in German ("du"), that's exactly what every translation will do.

It all works together

Here's what matters: glossary terms, formatting conventions, custom instructions, and formality settings all apply to every translation at the same time. You don't pick one or the other. You set them all up once, and every paragraph that gets translated goes through the same set of rules.

The result is translations that read like someone on your local team wrote them. Not like a machine that translated each sentence without knowing anything about your company.

Each language can have its own content

This is the feature that surprises people the most.

In this platform, a translated document isn't a locked copy of the original. Each language version can have content that only exists in that language.

Why does this matter?

Because different markets need different things:

Your German documentation might need a DSGVO (GDPR) compliance section that doesn't apply to the US version
Your Japanese team might need a note about local tooling nobody else uses
Your Brazilian office might need context about regional tax regulations

In most translation tools, adding content to one language version means it gets overwritten the next time someone retranslates from English. Teams figure this out fast and stop adding local content. They create shadow docs in Notion or Slack or somewhere else, and now you have two systems that nobody fully trusts.

In this platform, unique content is flagged as belonging to that language. It's never overwritten by retranslation. It's never deleted when the English source changes. It lives alongside the translated content as a natural part of the document.

Same goes for structure. If your Japanese translators prefer numbered lists where the English version uses bullets (a common convention in Japanese technical writing), they can change the format. this platform preserves that choice across future updates.

Every language version is a first-class document, not a read-only mirror.

Automatic and human: they work together

this platform doesn't force you to choose between machine translation and human translation. It supports both, and it knows the difference.

When a paragraph is machine-translated and the source changes, this platform retranslates it automatically. No human intervention needed. The glossary and style rules keep things consistent.

When a paragraph has been manually edited by a human translator, maybe they rewrote it for cultural nuance or added context a machine wouldn't catch, this platform respects that work. If the source changes, the system flags the paragraph as needing review but never silently overwrites human edits. The translator sees what changed in the source and decides how to update their version.

This means your translation quality improves over time. Machine translation handles the bulk. Human translators focus on the paragraphs that need a human touch. And neither one steps on the other's work.

Two modes: always current or translate on demand

For each language, you choose when translations happen:

Always translate. Every time someone saves the source document, changed paragraphs are retranslated immediately. Best for your most important languages where readers expect up-to-the-minute accuracy.
Translate when viewed. Changed paragraphs are flagged but not translated until someone actually opens the document in that language. Great for languages that are used less frequently. No wasted translation costs on content nobody is reading.

Both modes use the same glossary, the same style rules, the same quality. The only difference is timing.

What this looks like in practice

Say you run a company with teams in London, Munich, Paris, and Tokyo. Your documentation is written in English.

A product manager in London updates the deployment guide. One section about a new CI/CD step.

Here's what happens:

German (always translate). The changed section is retranslated within seconds. "Sprint Review" becomes "Sprint-Überprüfung" because that's in your glossary. Formal "Sie" because that's your formality setting. Dates in 24-hour format because that's your configured rule. The custom instruction "use a direct, imperative tone" shapes the phrasing. The DSGVO section the Munich team added? Untouched.
French (always translate). Same section, retranslated immediately. "Vous" formality. French glossary terms applied. Currency symbols after the number per your custom instruction. The rest of the document stays exactly as the Paris office last reviewed it.
Japanese (translate when viewed). The changed section is flagged as stale. When someone in Tokyo opens the document, it's translated on the fly. Their custom numbered-list formatting is preserved. Their local tooling note stays in place.

One edit. Three languages updated. Zero full-document retranslations. Consistent terminology, consistent tone, and respectful of every team's local additions.

Speaking of language quality

The translation engine behind all of this is DeepL, the same technology that powers this platform's Talk to Docs feature. You can speak to your documentation and get answers out loud. DeepL Voice handles the spoken interaction, which means the same terminology consistency, style rules, and language quality you get in written translations carries over to voice conversations too. Your glossary terms and custom instructions sound right whether your team is reading or listening.

Translations that sound like your team aren't a luxury. For companies operating across languages, they're the difference between documentation people trust and documentation people work around. Glossaries, style rules, custom instructions, smart retranslation, and per-language unique content make that possible. Automatically, from day one.

Your documentation should sound like your team in every language. Not like a machine. Not like a different company. Like you.

See multilingual publishing in action →

Inside the Translation Engine: Glossaries, Style Rules, and Smart Retranslation

2026-03-31T00:00:00Z

Our previous architecture post covered plugins, action guards, and the pipeline system. This one goes deeper into the translation engine, the part I think makes this platform fundamentally different from every other docs platform.

Not the marketing pitch about translating paragraphs instead of pages. The actual code. How glossaries are resolved per tenant, how DeepL's style rules and custom instructions shape every translation, how content hashing drives stale detection, and how the orchestrator decides which blocks to retranslate.

The translation pipeline

When a user saves a document, the system doesn't just retranslate everything. It runs a pretty specific sequence:

Parse the TipTap JSON into individual blocks
Compare content hashes to detect which blocks actually changed
For changed blocks, resolve the tenant's glossary and style rule list for the language pair
Apply style rules, custom instructions, and formality from tenant configuration
Send only changed blocks to DeepL
Update translation blocks and sync content hashes

Each step is its own service with its own interface. That matters because any step can be swapped out for something else, a different translation provider, a different hashing algorithm, a different glossary source.

Glossary resolution: tenant-scoped, DeepL-synced

DeepL glossaries have a constraint most people don't know about: they're immutable. You can't edit a DeepL glossary. Any change means deleting the old one and creating a new one.

this platform handles this by treating the database as the source of truth and DeepL glossaries as throwaway runtime artifacts. The TenantGlossary entity stores everything locally:

public class TenantGlossary : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string SourceLanguage { get; set; }     // e.g. "en"
    public string TargetLanguage { get; set; }     // e.g. "de"
    public string? DeepLGlossaryId { get; set; }   // Runtime DeepL ID
    public DateTime? LastSyncedAt { get; set; }
    public bool IsDirty { get; set; } = true;      // Triggers re-sync
    public ICollection<TenantGlossaryEntry> Entries { get; set; }
}

When a user adds a glossary entry, say mapping "Sprint Review" to "Sprint-Überprüfung" for EN→DE, the database record updates immediately and IsDirty gets set to true. The DeepL glossary isn't recreated right then. It gets recreated lazily, the next time a translation actually needs it.

The sync flow

Before every translation call, the system resolves the glossary:

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage,
    CancellationToken ct = default)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage, ct);

    if (glossary is null || glossary.Entries.Count == 0)
        return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty - delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var deepLGlossary = await _deepL.CreateGlossaryAsync(
        $"tenant-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = deepLGlossary.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return glossary.DeepLGlossaryId;
}

Three things worth noting here:

Lazy sync. We only hit the DeepL API when a translation is actually needed. Editing glossary entries in bulk doesn't trigger dozens of API calls.
Tenant isolation. The query runs through EF global query filters, so TenantGlossaries is automatically scoped. Tenant A's glossary entries never leak into Tenant B's translations.
One glossary per language pair. DeepL enforces this anyway. One EN→DE glossary, one EN→FR glossary, and so on. The (SourceLanguage, TargetLanguage) pair is unique per tenant.

Glossary entries

Individual entries are just term mappings:

public class TenantGlossaryEntry
{
    public Guid Id { get; set; }
    public Guid GlossaryId { get; set; }
    public string SourceTerm { get; set; }   // e.g. "Sprint Review"
    public string TargetTerm { get; set; }   // e.g. "Sprint-Überprüfung"
}

The API gives you full CRUD plus CSV import/export for bulk management:

POST   /admin/glossaries                       Create glossary
POST   /admin/glossaries/{id}/entries           Add term
PUT    /admin/glossaries/{id}/entries/{entryId}  Update term
DELETE /admin/glossaries/{id}/entries/{entryId}  Remove term
POST   /admin/glossaries/{id}/import            Import CSV
GET    /admin/glossaries/{id}/export            Export CSV
POST   /admin/glossaries/{id}/sync              Force DeepL sync

CSV import is super useful for teams migrating from existing translation memory systems. Export your terms, clean them up, import into this platform, and the next translation run uses the new glossary automatically.

Style rules, custom instructions, and formality

Glossaries handle terminology. But terminology is only half of it. A translation can use all the right words and still sound wrong. Wrong tone, wrong date format, wrong punctuation conventions.

DeepL's Style Rules API (v3) solves this. You can create reusable style rule lists that combine two types of controls:

Configured rules, predefined formatting conventions for dates, times, punctuation, numbers, and more
Custom instructions, free-text directives that shape tone, phrasing, and domain-specific conventions

this platform creates and manages these per tenant, per target language. The TenantStyleRuleList entity stores the DeepL style_id alongside the tenant's configured rules and custom instructions:

public class TenantStyleRuleList : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string TargetLanguage { get; set; }      // e.g. "de"
    public string? DeepLStyleId { get; set; }       // Runtime DeepL style_id
    public string ConfiguredRulesJson { get; set; }  // Serialized configured rules
    public bool IsDirty { get; set; } = true;
    public DateTime? LastSyncedAt { get; set; }
    public ICollection<TenantCustomInstruction> CustomInstructions { get; set; }
}

Creating style rule lists

When an admin sets up translation rules for German, this platform calls DeepL's v3 API to create the style rule list. Here's what that looks like:

public async Task<string> CreateOrSyncStyleRuleListAsync(
    TenantStyleRuleList ruleList, CancellationToken ct = default)
{
    if (!ruleList.IsDirty && ruleList.DeepLStyleId is not null)
        return ruleList.DeepLStyleId;

    // DeepL style rule lists are mutable - we can update in place
    if (ruleList.DeepLStyleId is not null)
    {
        // Replace configured rules on existing list
        await _httpClient.PutAsJsonAsync(
            $"v3/style_rules/{ruleList.DeepLStyleId}/configured_rules",
            JsonSerializer.Deserialize<JsonElement>(ruleList.ConfiguredRulesJson),
            ct);

        // Sync custom instructions
        await SyncCustomInstructionsAsync(ruleList, ct);

        ruleList.IsDirty = false;
        ruleList.LastSyncedAt = DateTime.UtcNow;
        return ruleList.DeepLStyleId;
    }

    // Create new style rule list
    var payload = new
    {
        name = $"tenant-{ruleList.TenantId}-{ruleList.TargetLanguage}",
        language = ruleList.TargetLanguage,
        configured_rules = JsonSerializer.Deserialize<JsonElement>(
            ruleList.ConfiguredRulesJson),
        custom_instructions = ruleList.CustomInstructions.Select(ci => new
        {
            label = ci.Label,
            prompt = ci.Prompt,
            source_language = ci.SourceLanguage
        })
    };

    var response = await _httpClient.PostAsJsonAsync("v3/style_rules", payload, ct);
    var result = await response.Content.ReadFromJsonAsync<StyleRuleResponse>(ct);

    ruleList.DeepLStyleId = result.StyleId;
    ruleList.IsDirty = false;
    ruleList.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return ruleList.DeepLStyleId;
}

Unlike glossaries, DeepL style rule lists are mutable. You can replace configured rules in place with PUT /v3/style_rules/{style_id}/configured_rules, and custom instructions can be individually added, updated, or deleted. Much friendlier for iterative refinement.

What configured rules look like

Configured rules cover formatting conventions that vary by language or company preference. Things like:

{
  "dates_and_times": {
    "time_format": "use_24_hour_clock",
    "calendar_era": "use_bc_and_ad"
  },
  "punctuation": {
    "periods_in_academic_degrees": "do_not_use"
  },
  "numbers": {
    "decimal_separator": "use_comma"
  }
}

These sound trivial, but they compound fast. A German document that uses AM/PM time format and period-separated decimals just reads as "translated from English" to a German reader. Setting use_24_hour_clock and use_comma for decimal separators across all German translations eliminates that immediately.

Custom instructions: this is the real power

Custom instructions are free-text directives, up to 200 per style rule list, each up to 300 characters. You basically tell DeepL how to shape the translation in plain language:

public class TenantCustomInstruction
{
    public Guid Id { get; set; }
    public Guid StyleRuleListId { get; set; }
    public string Label { get; set; }              // e.g. "Tone instruction"
    public string Prompt { get; set; }             // e.g. "Use a friendly, diplomatic tone"
    public string? SourceLanguage { get; set; }    // Optional source lang filter
}

Real examples from our tenants:

"Use a friendly, diplomatic tone" for a startup that wants approachable docs
"Always use 'Sie' form, never 'du'" for a German law firm
"Translate 'deployment' as 'Bereitstellung', never 'Deployment'" for terms that need context-dependent handling beyond simple glossary mapping
"Use British English spelling (colour, organisation, licence)" for UK-based companies translating between English variants
"Put currency symbols after the numeric amount" to match European conventions

Custom instructions are really powerful for domain-specific conventions that don't fit in glossary entries. A glossary maps one term to another. A custom instruction can say "when translating API docs, use imperative mood instead of passive voice." That's a completely different kind of control.

Formality

DeepL's formality parameter (default, more, less, prefer_more, prefer_less) is still available as a separate control alongside style rules. German "du" versus "Sie", French "tu" versus "vous", Japanese politeness levels. These are set per tenant language through TenantLanguageConfig:

public class TenantLanguageConfig : ITenantScoped
{
    public string LanguageCode { get; set; }
    public string DisplayName { get; set; }
    public bool IsEnabled { get; set; }
    public TranslationTrigger Trigger { get; set; }
    public string? Formality { get; set; }         // "more", "less", "prefer_more", etc.
    public string? StyleRuleListId { get; set; }   // Links to TenantStyleRuleList
    public string? TranslationProvider { get; set; }
    public int SortOrder { get; set; }
    public bool IsDefault { get; set; }
}

Formality, style rules, and glossaries all compose. A single translation call can carry all three:

var glossaryId = await GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang, ct);
var styleId = await GetOrSyncStyleRuleListAsync(targetLang, ct);
var formality = tenantLanguageConfig.Formality ?? "default";

// Build the v2/translate request payload
var payload = new
{
    text = new[] { blockContent },
    source_lang = NormalizeLanguageCode(sourceLang),
    target_lang = NormalizeLanguageCode(targetLang),
    glossary_id = glossaryId,
    style_id = styleId,
    formality = formality,
    preserve_formatting = true,
    context = surroundingContext,  // Adjacent blocks, not billed
    model_type = "quality_optimized"
};

Two things worth noting here:

The context parameter. We pass adjacent blocks as context to improve translation quality. DeepL uses this to resolve ambiguity but doesn't translate or bill for it. A paragraph about "cells" translates differently when the surrounding context is a biology document versus a spreadsheet manual.
Model selection. Any request with style_id or custom_instructions automatically uses DeepL's quality_optimized model. This is the highest quality tier. You can't combine these with latency_optimized, and that's a deliberate constraint by DeepL. Style customisation needs the full model.

Why this matters more than you'd think

Picture a company writing internal docs in German with informal "du" that suddenly switches to formal "Sie" in a translated section. Looks inconsistent at best, unprofessional at worst. Formality handles that. But formality alone won't catch a document that uses AM/PM timestamps when your German office uses 24-hour format, or that puts the currency symbol before the number instead of after.

All of these layered together (style rules, custom instructions, formality, glossaries) produce translations that read like someone on your team wrote them. Not like output from a machine that doesn't know your company exists.

The DeepL service layer

All DeepL communication goes through IDeepLService. It wraps the official DeepL .NET SDK and handles v3 API calls for style rules:

public interface IDeepLService
{
    // Text translation (v2)
    Task<TextResult> TranslateTextAsync(
        string text, string sourceLanguage, string targetLanguage,
        string? options = null);

    Task<TextResult[]> TranslateTextBatchAsync(
        IEnumerable<string> texts, string sourceLanguage,
        string targetLanguage, string? options = null);

    // Glossary management (v2)
    Task<GlossaryInfo> CreateGlossaryAsync(
        string name, string sourceLang, string targetLang,
        Dictionary<string, string> entries);
    Task DeleteGlossaryAsync(string glossaryId);
    Task<GlossaryInfo> GetGlossaryAsync(string glossaryId);
    Task<GlossaryInfo[]> ListGlossariesAsync();
    Task<Dictionary<string, string>> GetGlossaryEntriesAsync(
        string glossaryId);

    // Style rules (v3)
    Task<StyleRuleResponse> CreateStyleRuleListAsync(
        string name, string language,
        JsonElement configuredRules,
        IEnumerable<CustomInstructionRequest> customInstructions);
    Task ReplaceConfiguredRulesAsync(
        string styleId, JsonElement configuredRules);
    Task<CustomInstructionResponse> AddCustomInstructionAsync(
        string styleId, string label, string prompt,
        string? sourceLanguage = null);
    Task DeleteCustomInstructionAsync(
        string styleId, string instructionId);
    Task DeleteStyleRuleListAsync(string styleId);

    // Usage tracking
    Task<Usage> GetUsageAsync();
    Task<Language[]> GetSourceLanguagesAsync();
    Task<Language[]> GetTargetLanguagesAsync();
}

The implementation handles language code normalisation. DeepL requires EN-US or EN-GB instead of bare en, and PT-PT or PT-BR instead of pt:

private static string NormalizeLanguageCode(string code)
    => code.ToLower() switch
    {
        "en" => "EN-US",
        "pt" => "PT-PT",
        _ => code.ToUpper()
    };

Batch translation uses 50-item chunking to stay within DeepL's API limits while maximising throughput:

public async Task<TranslationBatchResult> TranslateBatchAsync(
    Dictionary<string, string> texts,
    string sourceLanguage, string targetLanguage)
{
    var translations = new Dictionary<string, string>();
    long totalChars = 0;

    foreach (var chunk in texts.Chunk(50))
    {
        var results = await _deepL.TranslateTextBatchAsync(
            chunk.Select(kv => kv.Value),
            sourceLanguage, targetLanguage);

        for (int i = 0; i < chunk.Length; i++)
        {
            translations[chunk[i].Key] = results[i].Text;
            totalChars += chunk[i].Value.Length;
        }
    }

    return new TranslationBatchResult
    {
        Translations = translations,
        BilledCharacters = totalChars
    };
}

Because we only send stale blocks, not entire documents, a typical translation batch for a single edit contains 1-3 blocks instead of 40+. That's where the 94% cost reduction comes from.

The translation orchestrator

The TranslationOrchestrator decides what to do with each block when the source document changes. Let's walk through the decision tree:

public async Task OrchestrateTranslationAsync(
    Guid entryId, List<Guid> changedBlockIds,
    CancellationToken ct = default)
{
    var entry = await _db.Entries
        .FirstOrDefaultAsync(e => e.Id == entryId, ct);

    var translations = await _db.EntryTranslations
        .Where(t => t.EntryId == entryId)
        .ToListAsync(ct);

    foreach (var translation in translations)
    {
        var langConfig = await GetLanguageConfigAsync(
            translation.Language, ct);

        var translationBlocks = await _db.TranslationBlocks
            .Where(tb => changedBlockIds.Contains(tb.SourceBlockId)
                      && tb.Language == translation.Language)
            .ToListAsync(ct);

        foreach (var block in translationBlocks)
        {
            if (block.IsLocked || block.TranslatedById is not null)
            {
                // Human-edited or locked - mark stale, don't overwrite
                block.Status = TranslationStatus.Stale;
            }
            else if (langConfig.Trigger == TranslationTrigger.AlwaysTranslate)
            {
                // Machine-translated, auto mode - retranslate now
                await RetranslateBlockAsync(block, translation.Language, ct);
            }
            else
            {
                // TranslateOnFirstVisit - mark stale, translate later
                block.Status = TranslationStatus.Stale;
            }
        }
    }

    await _db.SaveChangesAsync(ct);
}

The key bit: human-edited blocks are never automatically overwritten. If a translator manually adjusted a block, maybe adding cultural context or rewording for clarity, the system respects that work. It marks the block as stale so the translator knows the source changed, but it won't silently replace their edits.

Machine-translated blocks with AlwaysTranslate enabled are retranslated immediately. Machine-translated blocks with TranslateOnFirstVisit are marked stale and translated when someone actually opens the document in that language.

Translation triggers: when translations happen

Each language has a TranslationTrigger that controls timing:

public enum TranslationTrigger
{
    AlwaysTranslate,         // Translate on every save
    TranslateOnFirstVisit    // Translate when first opened in that language
}

AlwaysTranslate is useful for high-priority languages where you want translations to be immediately current. French for a company with a large Paris office. German for a company with headquarters in Munich.

TranslateOnFirstVisit is useful for languages that are occasionally needed but not worth the API cost of keeping perfectly current at all times. When someone opens the document in that language, stale blocks are translated on the fly.

Both modes use the same glossary resolution, the same formality settings, and the same content hashing. The only difference is timing.

Unique content and structure adaptation

This is where the architecture really pays off beyond just translation.

When a German translator adds a DSGVO compliance section that doesn't exist in English, they add it as a new block in the German version. That block has no SourceBlockId, it's flagged as unique content. The system never sends it for retranslation because there's no source to translate from. It only exists in German.

When a Japanese translator changes a bullet list to a numbered list (a common convention in Japanese technical writing), the block's IsStructureAdapted flag preserves this across future retranslation cycles:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    StructureAdaptationNotes = "Numbered list preferred in JP technical docs",
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

The IsNoTranslate flag handles content that should be copied verbatim: code blocks, URLs, product names, mathematical notation. The translation provider skips these entirely.

Putting it all together

Let's walk through the full flow. A user in London edits a paragraph in the English source document, and your Munich office has German set to AlwaysTranslate:

User saves. TipTap sends JSON to the API.
Block extraction and change detection. CreateBlocksFromDocumentAsync parses JSON, recalculates content hashes, and compares old and new hashes to identify which blocks actually changed.
Orchestrator runs. Finds the German EntryTranslation, checks the German block. It's machine-translated, not locked, not human-edited, so it's eligible for retranslation.
Translation config loaded. Glossary ID resolved via GetOrSyncDeepLGlossaryIdAsync("en", "de"), style rules via GetOrSyncStyleRuleListAsync("de"), formality set to "more" (formal "Sie"), adjacent blocks passed as context for disambiguation.
DeepL call. Single block sent with glossary ID, style ID, formality, and context.
Block updated. Translated content stored, SourceContentHash synced, status set to UpToDate. One block translated instead of 40+. The remaining 39 blocks? Untouched.

Meanwhile, your Tokyo office has Japanese set to TranslateOnFirstVisit. The same edit marks the Japanese translation block as Stale. When someone in Tokyo opens the document, steps 5-9 happen on the fly. Their structure adaptation (numbered list) is preserved. Their unique blocks stay exactly where they are.

I think the translation engine is the part of this platform that delivers the most visible value. Translations that use your terminology, follow your formatting conventions, obey your custom instructions, match your tone, respect your translators' work, and cost a fraction of what full-document retranslation would. The architecture makes all of that automatic, and stays out of the way when humans want to take over.

The same DeepL engine that powers written translations also powers Talk to Docs, our conversational documentation interface, with DeepL Voice handling the spoken interaction. Same glossaries, same style rules, same formality, same consistency. Whether your team reads documentation or talks to it, the language quality is identical.

Explore the translation API →

Stop Maintaining Five Copies of the Same Document

2026-03-31T00:00:00Z

Open your company wiki right now and search for "onboarding." How many results do you get?

If you're a global company, I'm guessing it's not one. It's probably something like this:

Onboarding Guide (EN)
Onboarding Guide - Germany
Onboarding Guide - Japan
Onboarding LATAM (draft)
Onboarding - New (DO NOT USE OLD ONE)

Five documents. All covering roughly the same thing. All slightly different. All maintained by different people on different schedules. Some current, some three months behind, one that nobody is sure about anymore.

This is what happens when your documentation platform can't handle multilingual content properly. You end up copying the whole document for every market, and each copy slowly drifts away from the others.

The copy-and-localise trap

It starts innocently enough. You have a great onboarding guide in English. The Berlin office needs it in German, so someone copies it, translates it, and adds the Germany-specific bits: DSGVO training, Betriebsrat information, local health insurance enrollment.

Then Tokyo needs one. Copy again. Translate. Add the Japan-specific stuff: hanko registration, commuter pass process, office etiquette guide.

São Paulo is next. Same thing. Copy, translate, add local content about CLT requirements, meal vouchers, and tax documents.

Now you have four documents. The English original gets updated regularly. The German version was updated last quarter. The Japanese version... someone thinks Tanaka-san updated it in October. The Brazilian version was created by a contractor who left, and nobody has touched it since.

Every copy is a maintenance burden. And every one of them contains a mix of shared content (the stuff that's the same everywhere) and local content (the stuff specific to that market). But the platform doesn't know the difference. It's all just text on a page.

So when someone updates the security policy section in the English original, nobody updates the other four. Or worse, someone updates the German one but not the Japanese one. Now you have five documents that all say slightly different things about the same company policy.

The real problem: shared and local content are mixed together

The thing is, most of these documents are 70-80% identical. The onboarding steps, the tools setup, the security policies, the company values section, the "who to contact" list. That's all the same regardless of whether you're in Berlin, Tokyo, or São Paulo.

The local stuff is maybe 20-30% of the document. Specific compliance requirements, local benefits, regional processes, team contacts for that office.

But when everything lives in one big flat document per language, there's no way to tell which parts are shared and which are local. An update to the shared content means manually checking and updating every copy. Which nobody does consistently. Which is why your copies drift.

One document. That's it.

In this platform, the onboarding guide is one document. Not one per language. One.

The shared content, the 70-80% that's the same everywhere, is written once in English and automatically translated into every language your team uses. When someone updates the security policy section in English, it's retranslated in German, Japanese, Portuguese, and French within seconds. No manual copying. No "someone should update the other versions."

The local content lives in its respective language version. The DSGVO training section exists only in the German version. The hanko process exists only in the Japanese version. The CLT requirements exist only in the Portuguese version. These sections are flagged as unique content, they belong to that language and are never overwritten by retranslation.

We covered exactly how this works in an earlier post about this translation approach. The short version: each paragraph has its own identity. Shared paragraphs are translated and tracked. Unique paragraphs belong to their language and nothing else touches them.

The result? Your wiki search for "onboarding" returns one result. Just "Onboarding." Open it in English, you see the English version with all shared content. Open it in German, you see the same shared content in German plus the Germany-specific sections. Open it in Japanese, same shared content in Japanese plus the Japan-specific sections.

One document. Not five. Not five documents slowly rotting at different speeds.

What this actually changes

This isn't just tidier. It fundamentally changes how your documentation works across offices.

Updates actually reach everyone

When you update the shared part of the onboarding guide, it's updated in every language. Not eventually, not after someone remembers to do it. Automatically. The paragraph you changed is retranslated. Everything else stays exactly where it was.

This means your Tokyo office is reading the same company policy as your London office. Not the version from six months ago that nobody got around to updating.

Local teams own their local content

Your Munich team can add a section about the local gym discount without worrying that it'll get wiped out by the next English update. Their unique content is theirs. It stays in the German version, untouched by any changes to the English source.

Same for every other office. Local content is genuinely local. It doesn't interfere with shared content, and shared content doesn't interfere with it.

New hires get the right information

A new hire in São Paulo opens the onboarding guide and sees everything they need. The shared sections (tools, security, values) are in Portuguese. The Brazil-specific sections (CLT, tax docs, meal vouchers) are right there alongside them. One document, everything in their language, nothing missing, nothing outdated.

They don't need to know that three other offices have different local sections. They just see their version. Clean and complete.

Your page count drops

This is the simple math. If you have 50 key documents and you maintain them in 5 languages with the copy-and-localise approach, you have 250 documents. In this platform, you have 50. Each with language versions that share common content and maintain their own local sections.

250 documents to maintain versus 50. That's 200 pages of maintenance overhead that just disappears.

It's not just onboarding

Onboarding is the obvious example because every global company has this problem. But the same pattern shows up everywhere:

Deployment guides. Core steps are the same, but the Berlin team uses a local staging server and Tokyo has a different approval process.
Compliance documentation. GDPR section for Europe, LGPD for Brazil, APPI for Japan. All in the same doc, each appearing only where it's relevant.
Benefits and HR policies. The parental leave policy is different in every country. The company values are the same everywhere.
Customer-facing help docs. The product works the same everywhere, but payment methods, support hours, and regional regulations vary.

Every one of these is a document that most companies maintain as separate copies per market. And every one of them could be a single document with shared and local content.

The compound effect

Here's where it gets real. A company with 200 documents across 4 markets isn't maintaining 200 docs. They're maintaining 800. But they're staffed for 200. So what actually happens is:

The English versions are current
The German versions are mostly current
The French versions are behind
The Japanese versions are a question mark

Sound familiar?

In this platform, they maintain 200 documents. The shared content is automatically translated. The local content is added by local teams. Every version is as current as the English one, plus whatever local additions the regional team has made.

The translation costs are lower too. When you update one paragraph in English, only that paragraph gets retranslated across all languages. Not the whole document, not all 200 documents. Just the paragraph that actually changed. I wrote about that approach in detail, including the glossary and style rules that make translated content sound natural.

A quick gut check

If you're running a global team, ask yourself:

How many duplicate documents do you have? Search for the same topic and count the language-specific copies.
How current are the non-English versions? Check the last-edited date on your German, French, or Japanese docs. How far behind are they?
Do local teams add content to their versions? Or have they given up because it gets overwritten?
How long does onboarding take in non-English offices? If it's longer, chances are the documentation isn't serving them properly.

If the answers make you uncomfortable, you're not alone. Most companies don't realise how much overhead they've created until they actually count the copies.

Documentation should scale with your company, not multiply. Every copy you maintain is a copy that can fall behind, confuse a new hire, or contradict the version someone else is reading. One document per topic, with shared content translated and local content where it belongs, is how documentation should work in a global company.

Your wiki shouldn't need five copies of the same document. One is enough. Shared steps translated, local steps per language. That's it.

See multilingual publishing in action →

The Business Case for Block-Level Localisation

2026-03-24T00:00:00Z

There's a pattern in every company that operates across borders. The English documentation is solid. The German version is three months behind. The Japanese version was translated once, by a contractor, and nobody has touched it since. The Brazilian Portuguese version doesn't exist yet, even though São Paulo is the fastest-growing office.

Everyone agrees this is a problem. Nobody has a good solution. Until now, localisation has been treated as a project, a one-time effort you budget for, execute, and then quietly neglect until the next big overhaul.

That approach is broken. Here's why, and what I think actually works.

Translation isn't localisation

Let's get the terminology straight. Translation is taking text in one language and producing equivalent text in another. Localisation is making knowledge work in a specific market. They overlap, but they're not the same thing.

A translated document reads correctly. A localised document reads naturally. It accounts for cultural context, regional regulations, local tooling, and the way people in that market actually work.

This distinction matters because most documentation platforms treat localisation as a translation task. You write in English, press a button, and get output in French. Done. Except it's not done, because:

The French team has a different deployment process that the English doc doesn't cover
German compliance requirements add an extra approval step that doesn't exist elsewhere
The Japanese office uses a different internal tool for the same workflow
Brazilian Portuguese readers need context about local tax rules that aren't relevant anywhere else

A straight translation of the English doc is technically correct in all of these cases, and practically useless in all of them too.

The problem with document-level translation

Traditional localisation works at the document level. You have an English document. You translate the entire thing into German. When the English version changes, you send the entire thing for retranslation. This creates three problems:

1. It's expensive

If your onboarding guide has 15 sections and you change one paragraph, you're paying to retranslate all 15 sections. Multiply that by 8 languages and every edit becomes a budget conversation.

2. It's slow

Sending complete documents for translation takes time. Even with modern machine translation, the review cycle for a full document is significantly longer than reviewing a single changed section. Teams in other languages are always running behind.

3. It doesn't support unique content

This is the real killer. If the German version needs an extra section about DSGVO compliance, where does it go? In a document-level translation system, any content added to the German version gets overwritten the next time someone retranslates from English. The German team learns fast: don't add anything, because it'll be wiped out.

Block-level localisation: a different architecture

this platform doesn't translate documents. It translates blocks: individual paragraphs, headings, and sections, each tracked independently with its own identity and content hash.

Here's what this means in practice:

When you edit a single paragraph in English, this platform detects which block changed by comparing SHA256 content hashes. Only that one block is sent for translation via DeepL. The other 14 blocks in the document stay exactly as they were. Your translation cost drops by up to 94%.

When the German translator needs to add a DSGVO section, they add it as a new block in the German version. That block exists only in German. It doesn't affect the English source. It doesn't get overwritten when English changes. It's flagged as unique content so everyone knows it's intentional.

When the Japanese version needs a different structure, say, a numbered list instead of bullet points because that's the convention in Japanese technical writing, the translator can change the block type. The system tracks this as a "structure adaptation" and preserves it across future updates.

Each language version becomes a first-class document, not a shadow copy.

How it works, technically

Every block in this platform has:

A UUID that persists across all edits and translations
A content hash (SHA256) that changes when the text changes
A position index so blocks stay in the right order
A soft-delete flag so removing a block in English doesn't break alignment in other languages

When a translation block is created, it stores the source block's content hash. On every save, the system compares hashes. If they match, the translation is current. If they don't, the translation is marked as stale, and only that specific block needs attention.

This is the mechanism behind the 94% cost reduction. Most edits change one or two sections. The rest of the document, across all languages, stays untouched.

Unique content per language

This is where things get genuinely different from any other platform.

In this platform, each language version can contain:

Translated blocks. Direct translations of the source language, tracked for staleness
Unique blocks. Content that exists only in that language, added by the local team
Structure-adapted blocks. Same source content, different formatting or block type

A single document might look like this across languages:

Block	English (source)	German	Japanese
1	Introduction	Translated	Translated
2	Setup steps	Translated	Structure adapted (numbered list)
3	-	DSGVO compliance (unique)	-
4	Deployment	Translated	Translated
5	-	-	Local tooling note (unique)
6	Troubleshooting	Translated	Translated

Every team gets exactly the documentation they need. No compromises. No workarounds. No one-size-fits-all limitations.

Freshness tracking across languages

Each language version tracks its own freshness independently. The English source might score 94 (recently reviewed, all links valid, high readership). The French version might score 71 (two stale blocks, one broken link specific to the French content). The Japanese version might score 88 (all translations current, but readership is declining).

This per-language freshness tracking means:

You know exactly which languages need attention
Stale translations are surfaced automatically, not discovered by accident
AI tools can factor in language-specific freshness when serving answers
Dashboards show content health broken down by language, not just by document

The business case

Companies that operate across languages face a simple reality: your documentation is either an asset or a liability in every market you serve.

When your Berlin team is working from a German translation that's three months behind the English source, they're making decisions based on outdated information. When your Tokyo office can't add local context to shared docs because the translation system would overwrite it, they stop using the wiki and create their own shadow documentation. When your São Paulo team doesn't have docs in Portuguese at all, onboarding takes twice as long.

The cost isn't just translation fees. It's:

Slower onboarding in non-English markets
Duplicated effort as teams maintain parallel documentation in local tools
Knowledge silos that form when the official wiki doesn't serve everyone
Compliance risk when region-specific requirements aren't captured
Lost trust in the documentation system itself

Block-level localisation solves all of these, not by making translation cheaper (though it does), but by making every language version a living, maintained, trustworthy document.

Getting started

If you're running a multilingual team on any documentation platform today, here's a quick gut check:

Pick your most important document. Check it in every language. Is each version current?
Ask your non-English teams: do they trust the translated docs? Do they use them?
Look for shadow documentation. Are teams maintaining local wikis, Notion pages, or Slack pinned messages because the official docs don't serve them?
Calculate your translation spend. How much are you paying per update, and how much of that is retranslating content that didn't change?

If the answers are uncomfortable, you're not alone. Most companies don't discover the gap until it causes a real problem: a compliance issue, a botched deployment, a new hire who spent two weeks following outdated instructions.

Multilingual knowledge isn't a nice-to-have. For any company that operates across borders, it's the foundation of how teams align, make decisions, and ship. The question is whether your documentation platform treats it that way.

Every language deserves to be a first-class citizen in your knowledge base. Not a copy. Not a shadow. A real, maintained, trusted document.

That is what this approach delivers: block-level translation, unique content per language, independent freshness tracking, and major translation cost reductions. All automatic. All from day one.

See multilingual publishing in action →

Content Freshness, Part 2: Beyond Expiry Dates

2026-03-18T00:00:00Z

This is Part 2 of our content freshness series. Part 1 covers why freshness matters and what it actually means. This post picks up where it left off: why expiry dates alone aren't enough, and what continuous monitoring looks like.

Let's say you do the responsible thing. Every document in your wiki gets a review date. Six months from creation, maybe twelve for stable reference material. When the date arrives, the owner gets a notification: review this or it gets flagged.

That's better than what most companies do. Most companies do nothing. The doc sits there, slowly decaying, and nobody notices until someone follows the instructions and something breaks.

But here's the uncomfortable truth: expiry dates are necessary and completely insufficient. I've seen documents go dangerously stale days after their last review, and a review date won't catch it.

What expiry dates actually solve

Expiry dates solve the accountability problem. They answer the question: "Who is responsible for confirming this is still accurate, and when?"

That's genuinely valuable. Without it, documentation enters what we call the ownership void, a state where everyone assumes someone else is maintaining it, so nobody does. Setting a review date assigns a single person a single obligation on a specific date. Simple. Clear. Effective.

Here's what expiry dates look like in practice:

A document is created with a review date 90 days out
14 days before expiry, the owner gets notified
On the expiry date, the document is flagged as "needs review"
The owner reviews, confirms it's still accurate, and extends the date
Or they update it, or reassign it, or archive it

This is a solid system. It catches the slow decay, the doc that nobody has thought about in a year. It creates a regular cadence of review. It makes ownership visible.

But it has a blind spot the size of a continent.

What expiry dates miss

Between review dates, a document lives in a black box. You reviewed it on January 15. The next review is April 15. On February 3, any of these things could happen:

Links break silently

An external URL you referenced returns a 404. An internal link points to a document that was archived. A code repository was renamed and every GitHub link in your doc is now dead. Your document still looks fine. The expiry date isn't for another two months. Nobody knows the links are broken.

Readership drops to zero

Your document used to be read by 40 people a month. Then a process changed and nobody needs it anymore, but nobody archived it either. It sits in search results, taking up space, occasionally confusing a new hire who doesn't know it's irrelevant. The expiry date doesn't care about readership. It'll ping the owner on schedule regardless.

Translations fall behind

The English source was updated on February 10. The French, German, and Japanese translations are now stale. But the expiry date on those translated versions isn't until May. For three months, non-English teams are reading outdated content and don't know it.

Readers flag problems

A reader leaves a comment: "Step 3 doesn't work anymore, the CLI flag was deprecated." That comment sits there. The expiry date is still weeks away. The next person who reads the doc might not see the comment. The one after that definitely won't.

Expiry is a scheduled checkpoint. These are unscheduled events. The gap between the two is where stale documentation does the most damage.

Freshness: continuous monitoring

Freshness scoring fills the gap that expiry dates leave open. Instead of checking a document's health once every 90 days, freshness tracks it continuously. Every day, in the background, without anyone needing to do anything.

Here's how it works in this platform:

Every document gets a live freshness score from 0 to 100, calculated from multiple signals:

Signal	What it detects	Why it matters
Link health	Broken, redirected, or unreachable URLs	Broken links erode trust and waste time
Review status	Whether the doc has been reviewed on schedule	The baseline accountability check
Readership trends	Whether anyone is actually reading this	Low readership suggests the doc may be irrelevant
Edit recency	When the doc was last modified vs. related content	Detects drift relative to the surrounding knowledge base
Translation alignment	Whether all language versions are current	Stale translations mean teams in other markets work from old info
Reader flags	Whether readers have reported issues	Crowdsourced staleness detection
Cross-references	Whether documents this one links to are themselves stale	Staleness is contagious

Each signal contributes to the overall score. A document can lose freshness points for a broken link today, even though its review date isn't for weeks. That's the whole point.

How the two work together

Expiry and freshness aren't competing approaches. They're complementary layers:

Expiry dates are the governance layer. They create a regular cadence of human review. Someone has to look at this document on a schedule and confirm it's still accurate. This catches the things automation can't: whether the content is still correct, whether the advice is still sound, whether the process it describes still reflects reality.

Freshness scoring is the monitoring layer. It catches everything between review dates: the broken links, the translation drift, the abandoned documents, the contextual decay that happens when the world moves and a document doesn't.

Together they create a system where:

Every document is reviewed by a human on a regular schedule (expiry)
Between reviews, automated signals catch problems as they happen (freshness)
Both systems feed into a single trust score that everyone can see
That score affects how the document ranks in search and whether AI tools use it as a source

The scoring impact

Here's where it gets practical. In this platform, a document's freshness score directly affects its visibility:

Score 80–100: Full visibility. Appears normally in search results. Eligible as a source for AI answers. No flags.
Score 50–79: Reduced visibility. Appears in search with a staleness indicator. AI tools may deprioritise it as a source. Owner is notified.
Score below 50: Flagged. Pushed down in search results significantly. Excluded from AI answers entirely. Owner receives urgent notification.

This creates a feedback loop. When a document's score drops, the owner is pushed to fix it, not because an arbitrary date arrived, but because something actually changed. The broken link, the stale translation, the declining readership, these are real signals that demand attention now, not in six weeks.

A practical example

Let's walk through a scenario:

March 1: Your "Incident Response Playbook" scores 92. It was reviewed two weeks ago, all links are valid, readership is high, and all four language versions are current.

March 8: Someone restructures the engineering status page. Three URLs in the playbook now redirect. Freshness score drops to 78. The owner gets a notification: "3 broken links detected."

March 10: The owner fixes the links. Score rebounds to 89.

March 15: The English version is updated with a new escalation path. The French and German translations are now stale (content hash mismatch). Score drops to 74.

March 17: The translations are updated. Score returns to 91.

March 20: Readership data shows the Japanese version hasn't been accessed in 30 days. Score dips to 86. A subtle signal, but tracked.

April 1: The scheduled review date arrives. The owner reviews the content, confirms it's accurate, extends the expiry to July 1. Score stays at 86 because the readership signal is still present.

At no point did the team wait for a review date to catch a problem. The freshness system flagged issues within days. The review date provided the governance checkpoint. Both layers doing their job.

Why "just set a review date" isn't enough anymore

Five years ago, expiry dates might have been sufficient. Documentation was read by people, and people can exercise judgement. If a doc looked a bit off, they'd ask around.

Today, documentation is infrastructure. It feeds AI tools, onboarding automation, compliance systems, and search engines that serve results without context. These systems don't exercise judgement. They consume content as-is and redistribute it at scale.

A document with broken links and stale translations that still has three weeks until its review date can do a lot of damage in those three weeks, especially if an AI assistant is confidently serving answers based on it.

Expiry dates are the minimum viable approach to documentation governance. Freshness scoring is what you need when documentation is consumed by systems that can't think for themselves.

Getting started

If you already have expiry dates on your documents (good for you, seriously, most teams don't even do that), here's how to layer on freshness:

Start tracking links. Run a broken link check across your top 50 documents. The number will probably surprise you.
Check translation alignment. If you have multilingual docs, compare last-edit dates between the source and translations. How many are more than a month behind?
Look at readership. Which documents get zero traffic? Are they still needed, or should they be archived?
Talk to your AI team. If you have an internal AI assistant, ask what documents it's sourcing from. Then check the freshness of those documents.

You'll likely find that your technically-not-expired documents have plenty of problems that expiry dates will never catch.

Expiry dates tell you if someone has checked a document recently. Freshness tells you if the document is actually healthy right now. One is a calendar event. The other is a living signal.

You need both. But if you only have expiry dates, you're flying blind between checkpoints.

A document doesn't go stale on its review date. It goes stale the moment something changes and nobody notices. Freshness scoring notices.

this platform combines mandatory expiry dates with continuous freshness monitoring. Every document earns its trust score, or loses it, in real time. No waiting, no blind spots, no surprises at review time.

See how freshness scoring works →

This is Part 2 of a two-part series. If you haven't read it yet, start with Part 1: The Metric Your Team Isn't Tracking.

Content Freshness, Part 1: The Metric Your Team Isn't Tracking

2026-03-16T00:00:00Z

There's a moment every engineering team has experienced. Someone finds a document on the internal wiki, follows the instructions, and something breaks. They message the channel: "Is this still accurate?" Nobody knows. The person who wrote it left eight months ago. The doc says it was last edited in 2024.

This is the freshness problem. And it's getting worse.

The old contract is breaking down

For a long time, documentation had an implicit contract: someone writes it, everyone trusts it, and occasionally someone updates it. Maybe. That contract worked, barely, when docs were consumed only by people who could apply judgement. If a setup guide looked a bit off, a senior engineer would just adapt on the fly.

But that world is over. Today your documentation isn't just read by humans. It's consumed by AI tools, internal chatbots, onboarding automation, and search systems that treat every word as equivalent truth. An AI assistant doesn't squint at a doc and think "hmm, this looks a bit dated." It reads the text, processes it as fact, and serves it with full confidence.

Stale documentation plus AI equals confidently wrong answers at scale.

What freshness actually means

Freshness isn't just "when was this last edited." A doc could be edited yesterday and still reference a deprecated API. True freshness is a composite signal:

Review status. Has someone explicitly confirmed this is still accurate?
Link health. Are the URLs inside the doc still resolving?
Readership. Is anyone actually using this, or has it been abandoned?
Contextual drift. Have related documents changed while this one stayed the same?
Translation alignment. If this exists in five languages, are all of them up to date?
Community signals. Have readers flagged this as outdated?

Each of these tells you something different. Together, they give you a trust score: a single number that represents how much confidence you should place in a piece of content right now.

Why this matters now, specifically

Three things have converged to make freshness urgent:

1. AI is consuming your knowledge base

Whether you've deployed an internal RAG system, use Copilot in your IDE, or have an AI assistant answering questions from your docs, the quality of the source material directly determines the quality of the output. Garbage in, garbage out has never been more literal.

When a developer asks your AI assistant "how do I deploy to staging?" and it answers using a two-year-old runbook that references infrastructure you've since migrated, the cost isn't just a wrong answer. It's lost trust in the entire system.

2. Teams are more distributed than ever

A team in Berlin, another in São Paulo, a third in Tokyo. All reading the same documentation, often in different languages. When the English source goes stale, every translation built on top of it goes stale too, but nobody notices because the translations are maintained separately, if at all.

3. Compliance and audit pressure is increasing

Regulated industries are starting to ask: "Can you prove this documentation was current at the time it was referenced?" If your answer is "well, someone probably checked it," that's not going to hold up.

What a freshness-first approach looks like

The core idea is simple: every document must continuously earn the right to be trusted.

This means:

Mandatory review dates. Every document gets an expiry date when it's created. No exceptions. When the date arrives, the owner is notified, and the document is flagged until someone explicitly re-approves it.
Automated health monitoring. In the background, the system continuously checks for broken links, readership trends, and contextual changes. These signals feed into a live score that updates without anyone having to do anything.
Freshness affects visibility. This is the key mechanism. A high-scoring document surfaces to the top of search results and is eligible to be used as a source for AI answers. A low-scoring document drops in ranking. If it falls below a threshold, it's excluded from AI answers entirely.
Transparency. Everyone can see why a document scored the way it did. Broken links, overdue review, low readership, the signals are visible, not hidden in a backend report nobody reads.

The cost of doing nothing

Here's what happens when you don't track freshness:

New hires follow outdated onboarding docs and spend their first week confused
AI tools serve wrong answers and nobody understands why
Compliance docs silently go stale and create audit risk
Translations drift out of sync and teams in different regions work from different versions of reality
Engineers stop trusting the wiki entirely and fall back to Slack messages, which creates its own knowledge silo

The compound cost of stale documentation is enormous, but it's invisible until something breaks.

A practical starting point

You don't need to overhaul everything at once. Start with these:

Audit your top 20 most-read documents. When were they last reviewed? Are the links still valid? Is the content still accurate?
Set review dates. Even if you do nothing else, putting a "review by" date on every document creates accountability.
Track what your AI tools are sourcing. If you have an internal AI assistant, look at what documents it's pulling from. Are those documents current?
Make freshness visible. Put the score where people can see it, next to the document title, in search results, in the sidebar. Visibility creates pressure to maintain.

Documentation freshness isn't a feature. It's a fundamental shift in how we think about organisational knowledge. In a world where AI tools consume and redistribute your docs at scale, the question isn't whether you can afford to care about freshness. It's whether you can afford not to.

Every document should have to prove it's still worth trusting. Not once. Continuously.

That is the direction modern documentation platforms should move toward: freshness as a foundation, not an afterthought. Review enforcement, live health scoring, freshness-weighted search, and AI answers that only use sources you can trust.

See how it works →

This is Part 1 of a two-part series. In Part 2: Beyond Expiry Dates, we explore how continuous freshness monitoring fills the gaps that review dates leave open.

Teach Your AI to Ignore Stale Documentation

2026-03-12T00:00:00Z

Here's what happens when you deploy an AI assistant on top of your internal knowledge base:

A new engineer asks: "How do I set up the staging environment?"

The AI searches your documentation, finds three relevant documents, synthesises an answer, and presents it with confidence. The engineer follows the instructions. The first two steps work. Step three references a CLI tool that was deprecated six months ago. Step four describes an infrastructure setup that was replaced during a migration nobody documented.

The engineer is stuck. They message the team channel. Someone says: "Oh, that doc is really old." The AI didn't know that. It can't know that. It just fetched everything it found and presented it as truth.

This is the default behaviour of every RAG system, every AI search tool, and every LLM-powered assistant you've ever used on internal docs. They fetch everything. They don't discriminate. They can't tell fresh from stale.

And it's destroying trust in AI tools faster than those tools can build it.

Why AI assistants are blind to quality

Large language models and retrieval-augmented generation (RAG) systems work by finding text that's semantically relevant to a query, then using that text to generate an answer. The relevance matching is usually excellent. Vector search and embeddings are genuinely good at finding content that relates to a question.

But relevance isn't the same as reliability.

A document written in 2023 about your Kubernetes deployment process is highly relevant to the question "how do I deploy to production?" It's also completely wrong if you migrated to a different platform in 2024. The AI sees relevant text. It doesn't see a document that's 18 months out of date with broken links and zero readership.

Most AI systems have exactly one ranking signal: semantic similarity to the query. That's it. They don't check:

When was this document last reviewed?
Are the links inside it still valid?
Is anyone actually reading this document?
Has the content been flagged by readers as outdated?
Is this a draft, an archived page, or a current document?
If this exists in multiple languages, are the translations current?

Without these signals, the AI is doing keyword matching with extra steps. Impressive keyword matching, yes, but fundamentally incapable of telling you whether the answer it's giving is based on content you can trust.

The confidence problem

This wouldn't be as dangerous if AI tools presented uncertain answers with appropriate caveats. But they don't. That's not how LLMs work. They generate fluent, confident text regardless of whether the source material is current or ancient.

A human reading a wiki article might notice it looks dated. The page layout is old. The screenshots show a UI that no longer exists. There's a comment at the bottom saying "this is outdated." A human can apply judgement.

An AI can't. It reads the text, processes it as equivalent to any other text, and generates an answer that sounds authoritative. The user, especially a new hire who doesn't know what the current process looks like, has no reason to doubt it.

The more confident the AI sounds, the more damage stale source material does.

What the AI actually needs

For an AI assistant to give trustworthy answers from your knowledge base, it needs more than text and embeddings. It needs metadata that tells it which documents are worth using as sources. Specifically:

1. Freshness score

A numeric signal that represents how healthy a document is right now. Not when it was last edited, that's just one input. A true freshness score combines review status, link health, readership, translation alignment, and contextual drift into a single number.

When a document scores above a threshold (say, 70 out of 100), it's eligible to be used as a source for AI answers. Below that threshold, it's excluded. No exceptions.

This single mechanism eliminates the most dangerous class of AI errors: confidently wrong answers based on stale sources.

2. Expiry status

Is this document currently within its review window, or has it expired without re-approval? An expired document should be heavily deprioritised or excluded entirely, regardless of how relevant its content might be to the query.

In this platform, expired documents are flagged and their freshness scores drop automatically. An AI system querying the knowledge base can see this status and act on it.

3. Classification labels

Not every document serves the same purpose. A draft shouldn't be used as a source. An archived document shouldn't appear in AI answers. An internal-only document shouldn't surface in queries from external-facing tools.

Classification labels give the AI context about what kind of document it's looking at:

Published. Current, approved, safe to use
Draft. Work in progress, should not be cited
Under review. Expiry triggered, awaiting re-approval
Archived. No longer active, kept for reference only
Internal / External. Controls visibility scope

When an AI assistant processes a query, it can filter by classification before even looking at content relevance. A draft document that perfectly matches the query should never be served as an answer.

4. Language-level signals

If your knowledge base is multilingual, the AI needs to know whether the version it's pulling from is current. A French translation that's three months behind the English source is technically relevant in French, but the information might be outdated.

this platform tracks freshness at the language level. Each translation has its own score based on whether its source blocks have changed since the translation was last updated. An AI querying the French knowledge base can see that the French version of a document is stale and either:

Fall back to the English source (which is current)
Include a caveat that the French version may be outdated
Exclude the document entirely

5. Reader signals

If multiple readers have flagged a document as outdated, that signal should reduce the document's weight in AI responses. Crowdsourced quality signals are noisy, but they're valuable, especially when combined with other freshness metrics.

How this works in practice

Let's walk through what happens when an AI assistant queries a this platform knowledge base:

Query: "What's our process for handling a P1 incident at 2am?"

Step 1: Retrieval with filtering. The system searches for semantically relevant documents. Before ranking, it filters out:

Documents with freshness score below the threshold
Expired documents that haven't been re-approved
Drafts and archived content
Documents whose language version is stale (if the query is in a non-primary language)

Step 2: Freshness-weighted ranking. Among the remaining documents, those with higher freshness scores rank higher. A document scoring 94 outranks one scoring 72, even if the 72-scored document has slightly higher semantic similarity.

Step 3: Answer generation. The AI generates an answer from the filtered, freshness-ranked sources. Every source is cited with its freshness score visible.

Step 4: Staleness warnings. If the best available source has a borderline freshness score, the AI includes a caveat: "Note: The primary source for this answer was last reviewed 60 days ago. You may want to verify with the team."

Compare this to the default behaviour: find relevant text, generate confident answer, hope for the best.

What happens when you don't do this

The consequences of AI systems operating on unfiltered knowledge bases are predictable and expensive:

New hire confusion. The most common AI use case for internal docs is onboarding. New hires, by definition, don't know what's current and what's stale. They trust the AI. The AI trusts everything. Stale docs get served with confidence.

Compliance exposure. If your AI assistant provides guidance on regulatory processes using outdated documents, the advice might not just be wrong, it might be non-compliant. "The AI told me to" doesn't hold up in an audit.

Erosion of trust. Every time the AI gives a wrong answer, users trust it a little less. After three or four bad experiences, they stop using it. The investment in AI tooling delivers no value because the underlying content wasn't trustworthy.

Shadow knowledge. When people lose trust in the official knowledge base (and the AI built on top of it), they create their own: Slack messages, personal notes, tribal knowledge shared in meetings. The fragmentation that the wiki was supposed to prevent happens anyway, just differently.

The fix is at the source, not at the model

There's a temptation to solve this at the AI layer: better prompts, more sophisticated RAG pipelines, fine-tuned models that can somehow detect staleness from text alone. This is the wrong approach.

The fix is at the source. If your documents carry rich, accurate metadata about their current state (freshness score, expiry status, classification, language alignment, reader signals) then any AI system can use that metadata to make better decisions. You don't need a smarter model. You need smarter documents.

This is what a freshness-first knowledge system provides:

Every document has a live freshness score that updates continuously based on link health, readership, review status, and more
Every document has an expiry date that triggers review when it arrives
Every document has a classification (published, draft, under review, archived)
Every language version has its own freshness signal so stale translations are detected independently
Reader flags and cross-reference tracking add additional quality signals

When an AI system queries a knowledge base that carries this metadata, all of this context is available. The AI doesn't have to guess whether a document is trustworthy. The document tells it.

A practical starting point

If you have an AI assistant running on your knowledge base today, you can start assessing the problem in 30 minutes:

Ask your AI assistant 10 questions you know the answers to. Note which answers use stale sources. You'll probably find at least 2-3 out of 10 are based on outdated content.
Check the source documents. For each answer the AI gave, look at the source document. When was it last reviewed? Are the links valid? Would you trust it if you read it yourself?
Look for the worst case. Find your oldest, most neglected document that still appears in search results. Ask the AI a question that would surface it. Does the AI use it? It almost certainly does.
Estimate the impact. How many queries per day does your AI assistant handle? If 20-30% of answers are based on stale content, what's the cost in terms of wasted time, wrong decisions, and lost trust?

AI assistants are only as good as the content they're built on. Right now, most of them treat every document in your knowledge base as equally valid. They fetch everything, the doc that was reviewed yesterday and the one nobody has touched in two years, and present it all with the same confidence.

That's not a model problem. It's a data quality problem. And the solution is straightforward: give your documents metadata that tells AI tools what to trust.

Your AI assistant shouldn't sound confident about an answer sourced from a document nobody has reviewed in 18 months. With the right signals, it won't.

this platform makes every document carry its own trust score: freshness, expiry status, classification, language alignment. AI tools query the knowledge base and get not just content, but context. Trusted sources surface. Stale ones don't. That's how AI-powered documentation should work.

See how this platform works with AI tools →

Talking to Documents Feels Better Than Reading Them

2026-03-10T00:00:00Z

There's a reason people say "let's talk it through" when something is complex.

When we're trying to understand a new idea, solve a problem, or recall a process under pressure, conversation often feels easier than reading. Not because reading is bad. Reading is one of the most powerful tools humans have ever developed. But reading is a learned skill layered on top of something much older: speech.

We're talkers long before we're readers.

That matters more than people realise, especially now that more of the world's knowledge lives inside documents, wikis, PDFs, and long internal pages that nobody wants to open unless they absolutely have to.

Reading is learned. Conversation is native.

Human beings spoke for a very long time before they wrote anything down. Children learn to understand spoken language naturally. Reading takes explicit instruction, repetition, and years of practice.

Even for highly literate adults, reading is still a more deliberate act than listening or speaking. It asks for visual focus, continuous attention, working memory, and interpretation of structure on the page. You're decoding symbols, parsing sentences, building context, and deciding what matters.

Conversation works differently. When information is delivered in a spoken, interactive form, the brain gets a different experience:

It feels sequential rather than visually overwhelming
It provides immediate feedback and clarification
It reduces the need to scan and filter large blocks of text
It mirrors how people already ask for help in real life

That last point matters a lot. Under uncertainty, most people don't instinctively want to read 1,500 words. They want to ask: "What do I do next?"

Talking lowers cognitive friction

A document is static. It contains everything at once.

That sounds useful, and often it is. But it also creates friction. A page full of headings, callouts, links, notes, examples, and edge cases forces the reader to decide what to ignore. That's cognitively expensive.

When you talk to an information system, you usually get the opposite experience: relevance first, detail second.

You ask one question. You get one answer. Then you ask a follow-up.

That interaction pattern reduces mental overhead in a few important ways:

1. It narrows the problem space

A full document presents the whole landscape. A conversation presents the next useful step.

When someone asks, "How do I onboard a new engineer?" they usually don't want the entire handbook immediately. They want orientation. Conversation lets them begin small and expand only when needed.

2. It preserves working memory

Reading requires you to hold multiple things in your head while looking for the relevant part. Spoken or conversational interaction externalises that effort. The system does more of the filtering for you.

3. It feels socially familiar

Humans are deeply adapted to back-and-forth exchange. We ask. Someone answers. We refine. They clarify. That loop is one of the oldest forms of learning we have.

Even when the "someone" is a system, the structure still feels natural.

Reading isn't passive. That's exactly the point.

One reason talking can feel easier is that reading isn't as effortless as people assume. Skilled readers make it look effortless, but the process is highly active.

To read well, you have to:

identify structure
infer importance
resolve ambiguity
keep context in memory
connect one section to another
decide when to skim and when to slow down

That's real cognitive work.

In many situations, that work is worthwhile. Deep reading helps with nuance, precision, and long-form understanding. But in other situations, especially when someone is tired, stressed, overloaded, or just trying to get unstuck, talking is often the mentally lighter option.

This is especially true in the workplace, where people aren't usually approaching documentation in ideal conditions. They are:

mid-task
interrupted
context-switching
trying to solve something quickly
often already slightly frustrated

In that state, conversational access to information can feel dramatically better than page-first access.

Speaking changes the relationship with information

There's also an emotional dimension here.

Documents can feel formal and distant. They imply: read all of this, understand it correctly, and don't miss anything important. That can be useful for reference material, but it can also create hesitation.

Conversation feels permissive. You can be vague. You can ask badly. You can admit confusion. You can say, "I don't really know what I'm looking for, but I need the thing about access requests."

That matters because people often avoid documentation not because they dislike information, but because they dislike the effort and uncertainty involved in finding the right part of it.

Talking reduces that barrier.

Why this matters now

For a long time, documents had to be read because there was no practical alternative. Search helped people find pages, but it did not change the interaction model. You still had to open the page, scan it, and extract what you needed.

That's changing.

As interfaces become more conversational, people are increasingly expecting information to respond rather than simply exist. They want to ask for what they need in plain language and receive something shaped to the moment.

This doesn't make reading obsolete. It changes its role.

Reading becomes the deep layer. Conversation becomes the access layer.

The best systems will support both:

talk when you need orientation or speed
read when you need depth, verification, or full context

The risk of oversimplifying

There's one important caveat: talking to information only feels better if the answers are reliable.

If a conversational interface gives partial, misleading, or overly confident answers, the experience becomes worse than reading because it removes the user's ability to inspect the source material directly.

So the future isn't "replace all documents with voice." The future is giving people a more human way to access documents without losing the depth and precision that written knowledge provides.

That balance matters. Conversation is easier, but documents still carry the durable structure, detail, and accountability that organisations need.

A more human interface to knowledge

The deeper point is simple: people don't naturally think in pages. They think in questions, stories, fragments, and dialogue.

We ask:

What does this mean?
What do I do first?
What's the important part?
Can you explain that differently?
What changed?

Those are conversational moves, not reading moves.

So when talking to information feels mentally easier than reading it, that's not a sign of intellectual laziness. It's usually a sign that the interface matches the way the brain prefers to approach uncertainty.

Reading remains essential. But as an entry point to knowledge, conversation often feels better because it's closer to what we are by nature.

We are not readers first. We are talkers first. The most intuitive knowledge systems will remember that.

Documentation Platforms Built for Another Era

2026-03-08T00:00:00Z

Confluence and Notion are not bad products. That needs to be said clearly at the start.

They succeeded for good reasons. Confluence became the default home for internal documentation in many companies because it gave teams a central place to write, organise, and share knowledge. Notion won people over with flexibility, cleaner writing experiences, and a more modern feeling product surface.

Both platforms solved real problems in the era they were built for.

The issue now is that the world around them has changed faster than their foundations.

We are no longer in a world where documentation just needs to be written, stored, and searched. We are in a world where documentation is increasingly expected to be:

machine-readable
freshness-aware
safe for AI retrieval
structured enough for automation
dynamic across languages and audiences
continuously trustworthy, not just available

That is a different bar.

They were built for a pre-AI model of knowledge

Traditional documentation platforms were designed around a simple assumption: if the page exists and is searchable, the problem is mostly solved.

That was good enough when the main user was a human opening a wiki, skimming the page, and applying judgement. In that model, the platform's job was to make authoring and navigation easier.

AI changes the job description.

Now the platform is not just storing knowledge for people. It is producing source material for systems that retrieve, rank, summarise, and answer questions automatically.

That introduces new requirements that older architectures did not prioritise:

Which content is trustworthy right now?
Which pages are stale but still searchable?
Which sections changed recently?
Which language version is current?
Which content is draft, archived, region-specific, or low-confidence?
Which documents should be excluded from AI answers entirely?

A platform that was not built around these questions has to retrofit them. That is always harder than designing for them from the start.

Legacy strength becomes legacy drag

Established products have advantages: distribution, ecosystem, brand, customer familiarity, integrations, and teams that know how to ship. But those same strengths can slow structural change.

Why? Because mature platforms carry commitments.

They have:

years of accumulated product decisions
huge installed bases with existing workflows
expectations around backward compatibility
plugins and extensions depending on old behaviour
data models optimised for yesterday's use cases

When a platform like Confluence or Notion wants to add a genuinely new capability, it often has to fit that capability around the existing system rather than through it.

That is the challenge of incumbency: you are not just building the future, you are dragging the past with you.

Adding AI features is not the same as becoming AI-native

A lot of established platforms are now layering AI on top. Summaries. Writing assistance. Search improvements. Q&A interfaces. Confluence has Atlassian Intelligence, Notion shipped Notion AI, and GitBook added AI-powered search. These are useful features. Some of them are good.

But there is a meaningful difference between:

adding AI features to a documentation product
building a documentation product whose core architecture assumes AI consumption from day one

The first approach often leads to assistive features around the edges. The second changes the foundation.

An AI-native knowledge platform asks different design questions from the start:

how should documents be structured so systems can reason about them safely?
how should trust be represented?
what metadata must be first-class, not optional?
how should stale content degrade in visibility?
how should answers be restricted when the underlying sources are weak?

Those are architectural questions, not feature questions.

Fresh platforms have a temporary advantage

This is where newer platforms can win, at least for a while.

A new platform has the freedom to design around today's constraints instead of yesterday's habits. It does not have to preserve a decade of assumptions about what a document is or how a wiki should behave. It can make different choices early:

treating freshness as a first-class concept
making source trust visible to both humans and machines
storing richer metadata about content state
building multilingual workflows into the core model instead of bolting them on
deciding that search and AI retrieval should rank by trust, not just relevance

That freedom matters.

In technology, incumbents are often strongest during stable periods. New entrants are often strongest when the model itself is shifting.

The AI era is one of those shifts.

Why this is especially hard for Confluence

Confluence is powerful, but it comes from an older worldview. It was built around team spaces, pages, hierarchical navigation, and a plugin-rich enterprise model. Those choices made sense. They still make sense for many organisations.

But they also mean the product is carrying a lot of complexity. Enterprise platforms rarely get to reinvent themselves cleanly. They have to negotiate with their own history.

That makes modernisation slower. Not impossible. Just slower.

When AI-era requirements call for cleaner metadata, more explicit trust modeling, or more opinionated content governance, a system built for maximal flexibility through years of extensions can struggle to move cohesively.

Why this is especially tricky for Notion

Notion has a different problem. It feels newer, lighter, and more flexible. But flexibility can also work against it.

Notion's strength is that almost anything can become a page, a database, a note, a lightweight doc, or a collaborative space. That flexibility is great for teams. It is less great when you need strong guarantees about what content means, what state it is in, and whether it should be used as a trusted source by an AI system.

The more free-form a platform is, the harder it is to impose reliable semantics later.

AI systems thrive on structure, explicit metadata, and confidence signals. Flexible general-purpose workspaces often need a lot of interpretation before their content is safe for that kind of use.

None of this means they are doomed

It would be lazy analysis to say Confluence and Notion cannot adapt. Of course they can.

They have smart teams, significant resources, and strong incentives. They will ship more AI capabilities. They will improve retrieval, authoring assistance, summaries, governance, and structured workflows. Over time, they may close a lot of the gap.

But timing matters.

When a shift like this happens, the advantage often belongs to whoever is willing to rebuild assumptions fastest. Newer platforms can move with more coherence because they are not retrofitting as much. That gives them a window.

It may not be a permanent window. But it is real.

The next phase of documentation platforms

The next generation of documentation tools will likely be judged less by how well they let people write pages and more by how well they manage knowledge as a trusted system.

That means the winners will probably do five things well:

They will model trust explicitly.
They will distinguish current knowledge from stale knowledge.
They will handle AI retrieval as a core product surface, not an add-on.
They will support multilingual and audience-specific knowledge without fragmentation.
They will give teams stronger control over what information is surfaced, to whom, and under what conditions.

That is a different category from the classic wiki.

Why fresh starts matter

There are moments in software when a clean-sheet product has an advantage not because incumbents are incompetent, but because history is expensive.

This is one of those moments.

A new platform can decide, from day one, that documents are not just pages. They are active sources for humans, agents, search systems, and AI assistants. That assumption changes everything downstream.

Confluence and Notion can get there. But the path is longer because they have to transform systems that were optimised for another era.

That transformation takes time. In the meantime, newer platforms have room to define what modern knowledge infrastructure should look like.

The biggest advantage of a fresh platform is not novelty. It is freedom from old assumptions at exactly the moment those assumptions stop working.

This is a perspective piece. Claims about competitor products are based on publicly available product documentation and announcements as of March 2026. We have genuine respect for both Confluence and Notion — they are excellent products that serve millions of teams well.

Inside the Architecture: Plugins, Action Guards, and Pipelines

2026-03-06T00:00:00Z

Most documentation platforms talk about "extensibility" the way airlines talk about "legroom." Technically present, practically disappointing. I wanted this platform's architecture to be genuinely extensible without becoming unpredictable, so we built three interlocking systems: plugins for capability, action guards for control, and pipelines for deterministic execution.

This post walks through how each one works in our actual codebase.

The plugin system: modular by design

Every plugin in this platform implements IPluginModule, a single interface that declares what the plugin is, what services it needs, and what routes it exposes:

public interface IPluginModule
{
    PluginManifest Manifest { get; }
    void RegisterServices(IServiceCollection services);
    void MapRoutes(IEndpointRouteBuilder routes);
}

The PluginManifest is pure data. It describes the plugin without executing anything:

public sealed class PluginManifest
{
    public required string Id { get; init; }
    public required string Name { get; init; }
    public required string Version { get; init; }
    public string Description { get; init; }
    public string Category { get; init; }
    public IReadOnlyDictionary<string, string> UiContributions { get; init; }
    public bool HasSettings { get; init; }
    public bool HasEndpoints { get; init; }
    public IReadOnlyList<string> Dependencies { get; init; }
}

Notice UiContributions. That dictionary maps frontend extension points to component names, so the Vue frontend knows which UI components each plugin contributes (a toolbar button, a sidebar panel, a settings page).

Registration is one line per plugin

At startup, we register plugins through a fluent API:

var pluginRegistry = new PluginRegistry();

pluginRegistry
    .AddPlugin<WorkflowPluginModule>(builder.Services)
    .AddPlugin<RulesPluginModule>(builder.Services)
    .AddPlugin<RetentionPluginModule>(builder.Services)
    .AddPlugin<ClassificationPluginModule>(builder.Services);

Each call instantiates the module, stores it in the registry, and calls RegisterServices() to wire up its dependencies. After the app builds, a single line maps all plugin routes:

app.MapPluginRoutes(pluginRegistry);

Under the hood, each plugin gets a scoped route group at /plugins/{pluginId}/ with authorization automatically applied.

Real example: the Workflow plugin

Here's what a real plugin looks like, the Workflow & Approvals module:

public sealed class WorkflowPluginModule : IPluginModule
{
    public const string PluginId = "workflow";

    public PluginManifest Manifest { get; } = new()
    {
        Id = PluginId,
        Name = "Workflow & Approvals",
        Version = "1.0.0",
        Description = "Adds approval workflows to entry publishing.",
        Category = "Workflow",
        HasSettings = true,
        HasEndpoints = true,
        UiContributions = new Dictionary<string, string>
        {
            ["entry.toolbar.publish"] = "WorkflowPublishButton",
            ["entry.sidebar.status"]  = "WorkflowStatusPanel",
            ["hub.admin.settings"]    = "WorkflowHubSettings",
        }
    };

    public void RegisterServices(IServiceCollection services)
    {
        services.AddScoped<IWorkflowService, WorkflowService>();
        services.AddScoped<IActionGuard, WorkflowPublishGuard>();
    }

    public void MapRoutes(IEndpointRouteBuilder routes)
    {
        WorkflowEndpoints.Map(routes);
    }
}

The core platform never references WorkflowService or WorkflowPublishGuard directly. It discovers them through the DI container. That's the key to zero coupling. The core app never touches plugin code.

Action guards: the control layer

Plugins add capability. Action guards decide whether that capability, or any core action, is allowed to proceed. They're synchronous validators that intercept operations before execution.

The interface is deliberately minimal:

public interface IActionGuard
{
    string PluginId { get; }
    string? ActionName { get; }  // null means guard ALL actions

    Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default);
}

When ActionName is null, the guard runs for every action. When it's set to something like "Entry.Publish", it only intercepts that specific action.

The context and result contracts

Every guard receives a typed context with the action name, tenant, user, entity, and a property bag:

public sealed record ActionGuardContext(
    string ActionName,
    Guid TenantId,
    Guid UserId,
    Guid EntityId,
    IReadOnlyDictionary<string, object?> Properties)
{
    public T? Get<T>(string key) =>
        Properties.TryGetValue(key, out var v) && v is T typed
            ? typed : default;
}

And every guard returns a predictable result: allow, deny, or allow-with-modifications:

public sealed record ActionGuardResult
{
    public bool IsAllowed { get; init; }
    public string? ReasonCode { get; init; }
    public string? Message { get; init; }
    public IReadOnlyDictionary<string, object?>? Modifications { get; init; }

    public static ActionGuardResult Allow() =>
        new() { IsAllowed = true };

    public static ActionGuardResult Deny(
        string reasonCode, string message) =>
        new() { IsAllowed = false, ReasonCode = reasonCode, Message = message };
}

The Modifications field is important. A guard can approve an action but rewrite part of the content (for example, redacting secrets before publish).

Canonical action names

We define all interceptable actions as string constants so there's zero ambiguity about what a guard can target:

public static class ActionNames
{
    public static class Entry
    {
        public const string Create  = "Entry.Create";
        public const string Save    = "Entry.Save";
        public const string Publish = "Entry.Publish";
        public const string Delete  = "Entry.Delete";
        public const string Archive = "Entry.Archive";
        public const string Renew   = "Entry.Renew";
    }

    public static class Hub
    {
        public const string Create = "Hub.Create";
        public const string Delete = "Hub.Delete";
        public const string TransferOwnership = "Hub.TransferOwnership";
    }

    public static class Translation
    {
        public const string Create  = "Translation.Create";
        public const string Publish = "Translation.Publish";
    }
}

Real example: blocking publish without approval

The Workflow plugin registers a guard that intercepts Entry.Publish:

public sealed class WorkflowPublishGuard : IActionGuard
{
    public string PluginId => WorkflowPluginModule.PluginId;
    public string? ActionName => ActionNames.Entry.Publish;

    public async Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default)
    {
        var db = services.GetRequiredService<RasepiDbContext>();
        var entry = await db.Entries
            .AsNoTracking()
            .FirstOrDefaultAsync(e => e.Id == context.EntityId, ct);

        if (entry is null)
            return ActionGuardResult.Allow();

        var workflowService = services.GetRequiredService<IWorkflowService>();
        var check = await workflowService
            .CheckPublishAllowedAsync(entry.Id, entry.HubId);

        if (check.IsAllowed)
            return ActionGuardResult.Allow();

        return ActionGuardResult.Deny(
            "workflow.approval_required",
            check.Message ?? "Approval required before publishing.");
    }
}

The core platform knows nothing about approval workflows. It just calls Entry.Publish through the pipeline, and the guard blocks it if the workflow hasn't been completed.

The action pipeline: where everything converges

The ActionPipeline is the single execution path for all guarded operations. It resolves which guards apply, evaluates them, and either blocks or executes the action.

public sealed class ActionPipeline : IActionPipeline
{
    public async Task<ActionPipelineResult> ExecuteAsync(
        string actionName,
        ActionGuardContext context,
        Func<Task> action,
        CancellationToken ct = default)
    {
        var result = await EvaluateAsync(actionName, context, ct);
        if (!result.IsAllowed) return result;

        await action();  // All guards passed — execute

        return result;   // Return modifications for caller
    }
}

The EvaluateAsync method does the heavy lifting:

public async Task<ActionPipelineResult> EvaluateAsync(
    string actionName,
    ActionGuardContext context,
    CancellationToken ct = default)
{
    // 1. Which plugins are enabled for this tenant?
    var enabledPlugins = await _resolver.GetEnabledPluginIdsAsync();

    // 2. Which guards match this action?
    var applicable = _guards
        .Where(g => enabledPlugins.Contains(g.PluginId))
        .Where(g => g.ActionName == null || g.ActionName == actionName)
        .ToList();

    // 3. Evaluate each guard
    var denials = new List<ActionGuardResult>();
    var modifications = new List<ActionGuardResult>();

    foreach (var guard in applicable)
    {
        try
        {
            var guardResult = await guard.EvaluateAsync(context, _services, ct);
            if (!guardResult.IsAllowed)
                denials.Add(guardResult);
            else if (guardResult.Modifications?.Count > 0)
                modifications.Add(guardResult);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Guard threw. Treating as Allow.");
        }
    }

    // 4. Any denial blocks the whole action
    if (denials.Count > 0)
        return ActionPipelineResult.Blocked(denials);

    return modifications.Count > 0
        ? ActionPipelineResult.Allowed(modifications)
        : ActionPipelineResult.Allowed();
}

Three important design decisions here:

Per-tenant resolution. The TenantPluginResolver checks which plugins each tenant has installed and enabled. A guard for a disabled plugin never runs.
All-must-pass. If any guard denies, the action is blocked. This is a deliberate security stance.
Guard errors fail open. If a guard throws an exception, it's logged and treated as Allow(). This prevents a broken plugin from locking the entire platform.

Per-tenant plugin resolution

The resolver queries the TenantPluginInstallations table (automatically scoped to the current tenant by EF global query filters):

public sealed class TenantPluginResolver : ITenantPluginResolver
{
    public async Task<IReadOnlySet<string>> GetEnabledPluginIdsAsync(
        CancellationToken ct = default)
    {
        if (_cache is not null) return _cache;

        var ids = await _db.TenantPluginInstallations
            .Where(i => i.IsEnabled)
            .Select(i => i.PluginId)
            .ToListAsync(ct);

        _cache = ids.ToHashSet();
        return _cache;
    }
}

Event-driven side effects

Actions are synchronous. Side effects aren't. After an action completes, the service publishes a domain event:

await _eventPublisher.PublishAsync(
    EventNames.Entry.Created, entry.Id, new { entry.OriginalLanguage });

Events are enqueued to an in-memory channel and processed by a background EventConsumerWorker. The worker routes events to multiple systems:

Activity tracking. Logs who did what, when
Translation billing. Tracks costs per provider
Plugin event handlers. Any plugin can subscribe to domain events

Plugin event handlers implement IPluginEventHandler:

public interface IPluginEventHandler
{
    string PluginId { get; }
    IReadOnlyList<string> SubscribedEvents { get; }

    Task HandleAsync(
        string eventName, Guid entityId,
        Guid? tenantId, Guid? userId,
        string payloadJson, IServiceProvider services,
        CancellationToken ct = default);
}

The worker only invokes handlers whose plugin is enabled for the tenant. This means plugin A's side effects never leak into a tenant that only has plugin B installed.

The block-level translation engine

This is where the architecture pays off most visibly.

Traditional platforms translate entire documents. We translate individual blocks: paragraphs, headings, list items. When a user edits one paragraph in a 50-block document, only that paragraph needs retranslation. That's the source of our 94% cost savings.

How blocks are created from TipTap JSON

When a user saves a document, the TipTap editor sends JSON like this:

{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "attrs": { "blockId": "a1b2c3d4-..." },
      "content": [{ "type": "text", "text": "Hello world" }]
    }
  ]
}

The BlockTranslationService parses this JSON and creates individual EntryBlock records:

public async Task<List<EntryBlock>> CreateBlocksFromDocumentAsync(
    Guid entryId, string language, string contentJson,
    int version, Guid userId)
{
    var doc = JsonDocument.Parse(contentJson);
    var content = doc.RootElement.GetProperty("content");

    int position = 0;
    foreach (var node in content.EnumerateArray())
    {
        var blockType = node.GetProperty("type").GetString();
        var blockJson = JsonSerializer.Serialize(node);

        // Strip metadata attrs before hashing
        var hashInput = StripBlockMetaAttrs(blockJson);

        var block = new EntryBlock
        {
            Id = ExtractOrGenerateBlockId(node),
            EntryId = entryId,
            Language = language,
            Position = position++,
            BlockType = blockType,
            ContentJson = blockJson,
            ContentHash = CalculateContentHash(hashInput),
            IsNoTranslate = ExtractNoTranslateFlag(node),
            Version = version,
        };

        _context.EntryBlocks.Add(block);
    }

    await _context.SaveChangesAsync();
    return blocks;
}

SHA256 hashing for stale detection

The content hash is the core of stale detection. We hash the block content (after stripping metadata attributes like blockId and deleted) using SHA256:

private string CalculateContentHash(string content)
{
    using var sha256 = SHA256.Create();
    var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(content));
    return Convert.ToHexString(hashBytes);
}

When a source block changes, its hash changes. The system then compares every translation block's SourceContentHash to the current source hash, and mismatches are marked Stale:

public async Task MarkTranslationsAsStaleAsync(List<Guid> changedBlockIds)
{
    var affected = await _context.TranslationBlocks
        .Where(t => changedBlockIds.Contains(t.SourceBlockId))
        .ToListAsync();

    foreach (var translation in affected)
    {
        translation.Status = TranslationStatus.Stale;
        translation.UpdatedAt = DateTime.UtcNow;
    }

    await _context.SaveChangesAsync();
}

Structure adaptation

Translators can change block types across languages. An English bullet list might become a German numbered list, a cultural preference. The system tracks this:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

Translation providers as plugins

External translation services (DeepL, Google Translate, etc.) plug in through ITranslationProviderPlugin:

public interface ITranslationProviderPlugin : IRasepiPlugin
{
    string[] GetSupportedLanguages();

    Task<string> TranslateAsync(
        string text, string sourceLanguage, string targetLanguage);

    Task<TranslationBatchResult> TranslateBatchAsync(
        Dictionary<string, string> texts,
        string sourceLanguage, string targetLanguage);
}

The batch method receives a dictionary of block IDs to content, translates them all, and returns the translations with a billed character count. Because we only send stale blocks, not the entire document, costs stay minimal.

Tenant isolation: the invisible safety net

Every system described above runs inside strict tenant isolation.

The TenantContextMiddleware resolves the tenant from the JWT on every request and verifies membership:

public async Task InvokeAsync(
    HttpContext context, TenantContext tenantContext, RasepiDbContext db)
{
    var tenantIdClaim = context.User.FindFirstValue("tenant_id");
    var userIdClaim = context.User.FindFirstValue(ClaimTypes.NameIdentifier);

    // Populate scoped context
    tenantContext.TenantId = Guid.Parse(tenantIdClaim);
    tenantContext.UserId = Guid.Parse(userIdClaim);

    // Verify membership — fail closed
    var membership = await db.TenantMemberships
        .Where(m => m.TenantId == tenantContext.TenantId
                  && m.UserId == tenantContext.UserId)
        .FirstOrDefaultAsync();

    if (membership == null)
    {
        context.Response.StatusCode = 401;
        return;  // No membership = no access
    }
}

Entity Framework global query filters ensure that even if a developer forgets to filter by tenant, the database layer does it automatically:

modelBuilder.Entity<Hub>()
    .HasQueryFilter(h => h.TenantId == _tenantContext.TenantId);

The result: db.Hubs.ToListAsync() always returns only the current tenant's hubs. Data leaks require actively bypassing the query filter, which is banned in our codebase.

The full picture

When a user clicks "Publish" on an entry, here's what happens:

Request enters. Authentication validates the JWT, TenantContextMiddleware resolves and verifies the tenant.
Controller calls pipeline. IActionPipeline.ExecuteAsync("Entry.Publish", context, action)
Pipeline resolves guards. Queries which plugins the tenant has enabled, selects applicable guards.
Guards evaluate. The Workflow guard checks for approvals, the Retention guard checks for policy, the Rules guard validates content. All pass? The entry is published.
Events fire. Entry.Published event is enqueued. A background worker logs activity, updates translation billing, and calls plugin event handlers.
Block translations checked. Stale blocks are identified for retranslation.

Each layer does its job. No layer reaches into another. That's the architecture.

We didn't build this because extensibility is trendy. We built it because a documentation platform that can't adapt to each team's workflow will eventually be replaced by one that can. And a platform that adapts without guardrails will eventually break something that matters.

Dev Tunnels vs NGrok

2024-02-29T00:00:00Z

Taken from https://devblogs.microsoft.com/visualstudio/dev-tunnels-in-visual-studio-for-asp-net-core-projects/

	Visual Studio Dev Tunnels	NGrok
SSL/HTTPS
tunnels	unlimited	1 per license 2 per agent (more for paid)
TCP Connections	?	up to 100
bandwidth restriction	? (likely unlimited)	1 GB / monthly
Maximum uptime	unlimited	2 hours (free)
Authentication		(Paid only, 50 MAU)
request log
replay requests
inspect requests
random URLs
custom URLs		(Paid only)
durable URLs	(Might not be reliable)
automatically start/stop

(All as of writing this article in January 2023, table is subject to change)

Visual Studio 2022 Preview 3 is here!

2023-01-21T00:00:00Z

Visual Studio 2022 Preview 3 was released a few days ago and is packed with quite a few nice updates now (including Preview 1 + 2 features).
The new release comes with quite some handy features and shows yet again that Microsoft is actually listening to the community! You can find all community suggestions that
made it into the release here! Working with API's got some huge quality-of-life upgrades but also some handy tools for developers working on integrations,
plugins, or mobile apps last but not least you now have a nice integrated markdown editor for those pesky readme files!

Let's have a look at some of what I think are the most useful ones in no specific order:

Integrated Markdown editor (Community suggestion!)

Despite being added in preview 2 the markdown editor is now available for everyone and always enabled per default. You can now easily and conveniently edit those
readme.md files or other pieces of documentation you might have, inside Visual Studio!

Nice feature on top - Spell checking works in markdown as well :)

DevTunnels

Those of you who have been working on any plugin, integration, MS Teams extension, or similar might know the need for a tunnel to your locally running Visual Studio.
In past I've been using NGROk for that which does its job quite well but is an external tool to use, you have to set it up, etc.
Now Visual Studio comes with an integrated way of achieving the same the so-called "DevTunnels".
After configuring a tunnel it starts and stops with your application and you don't have to care about that. It even comes with inbuilt authentication!

Let's have closer look.

After enabling Developer Tunnels in the preview options you'll find a new entry in the context menu below:

From here you can manage your Tunnels easily. Adding a new tunnel is quite simple, you can give it a name for
yourself to recognize it, you can configure authentication options and persistence. Based on the official preview docs the
persistent URL should stay for the lifetime of the tunnel but we have not tried that yet.

The "Access" setting is also quite handy, you can set it to public which is not recommended, you can also set it to private which
only allows access for yourself and you can set it to organizational which allows anyone who's in your tenant to access it.

Organizational however does only work with an M365 account and does not work with Github.

After setting up the tunnel you get a new windows showing the current state, this also gives you the URLS that have been generated, you can only
remove the tunnel here. Everything else is tied to your project. When you start the project the tunnel is automatically started as well, no manual steps
involved!

For me this is a huge game changer as I no longer have to deal with Ngrok, make sure its started, etc and it also covers securing your work on top. Nicely done!

Colorized Tabs (RegEx based!)

One of the new features I like the most as it really helps me get some more structure in my work is the colorized tabs feature. It is not completely new but got quite an update.
You can now colorize (and group) tabs based on regex! This allows you for example to give all your controllers a specific color or separate model from a controller, JS from C# files, etc
etc it's really powerful and up to you! Another nice feature is, its configured in a .txt file means you can have different settings per repository you're working on!

Its simple to enable:

After enabling that there's a new "Configure Regex" option which leads to this:

For myself, I separated extensions, controllers, and middleware as that's what I'm constantly working on for my APIGenerator

^.*\\*Extension\.cs$
^.*\*Controller.cs$
^.*\*Middleware.cs$

ASP.NET Output in the integrated terminal (yay!)

When working with WebAPI etc you often had tons of console windows flying around, at least always one.
This was now changed as Visual Studio no longer opens a new console window but shows the
output of your app directly in the integrated terminal. When you have multiple projects, each will get its own terminal window and you can easily switch between them.

WebAPI Endpoint Explorer

One nice feature I didn't even know about as its not listed in the official preview docs is the new Endpoint Explorer. (Thanks Hassan for sharing!)
The new view parses your controllers at compile/coding time and lets you navigate all your endpoints directly from here.
It brings you to the corresponding functions by clicking on it and gives a nice overview.

I don't know what the plans are for this, to be useful it definitely needs to have a few more features (like testing those endpoints!)
But its a first start, if you combine that with the .HTTP files explained further below its a handy addition and shows what
might come in future so stay tuned!

(Thanks Hassan Habib for the gif!)

.HTTP Files for easy REST call testing

Its been around for a while but not well known so I include that here. Visual Studio 22 now has a lovely feature to quickly test
your live endpoints or just try things.

If you create a .HTTP file you can perform API calls directly from that file as seen in the gif below

(Thanks Hassan Habib for the gif!)

The HTTP calls in here are really simple to use, just write

<METHOD> <Endpoint>
such as
GET https://api.github.com/xxxx

If you need more parameters or are testing a POST/PUT etc call you can add more parameters in the lines below:

POST https://api.github.com/xxxx
Content-Type: application/json
{
  "username": "testuser",
  "password": "testpassword"
}

A handy little feature that makes your life a bit easier. I'll cover more about that in a detail article soon.

Colorized brace pairs is here! (C++ only for now)

Nothing too special for me personally but an honorary mention is the new colorization feature for braces,
various nesting levels and scopes can now have a different color making
code navigation is quite a bit simpler. I'll properly test that once its available for C# which is at least
announced.

All-In-One Search results

Visual Studio now lets you search for whatever you want in your code and in Visual Studio functionality as well! Simply type what you're looking for and you get all
matching results, search for something in your code and it navigates you right to it. If you search for a VS Window or option it takes you straight to the options dialog or
opens the window you've been asking for!

There's a ton more new features I did not cover yet such as added and improve spell checking (fix those comments!), improvements when working with container images, quick add new files or sticky scroll when editing code files. All I can say is, VS keeps getting better and better every day!

I'll cover some topics later in detail so stay tuned!

Adaptive Cards, what else can you use them for?

2022-08-30T00:00:00Z

Adaptive Cards, what else can you use them for?

As usual, if you don’t know what Adaptive Cards are you probably want to read a bit about them first. The easiest start is by just going to www.adaptivecards.io, play a bit with the designer there, have a look at the samples and get a feeling what all this is about. Just come back here whenever you’re done and don’t forget me :)

Many people think Adaptive Cards is something Microsoft invented to be used in MS Teams or Power Platform and the alike and while that is totally true it's only half the picture. Adaptive Cards and the technology behind, including the templating engine, can be used for so much more!

Let's just have a closer look at what the website says here:

Adaptive Cards are platform-agnostic snippets of UI, authored in JSON, that apps and services can openly exchange. When delivered to a specific app, the JSON is transformed into native UI that automatically adapts to its surroundings.

That, to me, doesn’t necessarily say anything about any Microsoft product as such. No! You can use it in your apps, your websites, your mobile apps. Basically, wherever you like and everything you need to do so is included in the library itself on Github, NPM or Nuget. (https://www.github.com/microsoft/adaptivecards)

In the last year, as part of my work for Teamwork.com we used Adaptive Cards for various things. Our MS Teams App (available in Beta, just ask us ) is using cards for various notifications and UI pieces.

The Visual Studio Code Extension is fully made with Cards and was showcased during Build and MS Ignite last year. If you want to have a look, here it is:
https://github.com/Teamwork/vscode-projects
https://marketplace.visualstudio.com/items?itemName=Teamwork.twp

Isn’t that still a Microsoft product?

So… yea someone said to me on Ignite, its great yea but VSCode is still a Microsoft product. Even if VS Code is Electron-based, yea maybe true. I get that. However, I have more to talk about for you :)

This is a screenshot of one of our upcoming desktop apps. Written in Electron and vue.js. We used Adaptive Cards here to show some file details and allow adding comments on files.

Teamwork Document Editor V2 using Adaptive Cards for a few features

Its again, similar to VS Code obviously an Electron app, the same thing again and before someone says anything, let's get a bit crazier :)

Why not build a somewhat full app UI with basically just Adaptive Cards?

Yeah right, sounds crazy, some people might not even think that's doable but here we are, have a look at these two screenshots:

Person listing, made with just Bootstrap and Cards

Adaptive Card used to grab person details

In the last roughly one hour I build an example app you can see on the screenshots. The only things this app is using are Bootstrap, Vue.JS and Adaptive Cards. There’s no input field or anything in the code itself, Vue.js is only used for routing and data/state management, Bootstrap for grid and positioning.

The app is mainly made with two cards, one for the list view and the other one for edit/create.

List Card: https://github.com/DeeJayTC/AdaptiveCardsPeopleApp/blob/master/AdaptiveCardsVuePeople/src/assets/personCard.json

Edit Card: https://github.com/DeeJayTC/AdaptiveCardsPeopleApp/blob/master/AdaptiveCardsVuePeople/src/assets/personCreate.json

We can use the same card for edit and create as the templating engine will omit empty values and just show the placeholder, when showing the create modal we sent no data and the templating engine automatically just shows the placeholder and no value.

{
    "type": "Input.Text",
    "placeholder": "Person full name",
    "value": "{$root.displayName}",
    "id": "name"
},

But lets just not talk about stuff, demo’s are the best proof, just have a look at this, the full app available and working online: https://deejaytc.github.io/AdaptiveCardsPeopleApp/

Full source available here: https://github.com/DeeJayTC/AdaptiveCardsPeopleApp

Now, why am I talking to you about this?

Well, as said in the beginning, Adaptive Cards and everything related is a lot more than just a technology used for Microsoft products. It's highly flexible and can be used for a ton of things. This article pretty much should just explain that you can do more with Cards than you might have thought by now.

Just start thinking…what else can I use this for? I’m sure you’ll find a few great things.

Let me know what you use Cards for today and let's talk!

CRUD API's in an instant

2022-03-31T00:00:00Z

Want an easy way to build a CRUD API?

Building an API with .NET can be quite time consuming as there is a lot of boilerplate code you usually have to deal with. Controllers, EntityFramework, Models, Routes....
and whatever else comes to your mind. However, it doesn't have to be like this and can actually be done lightning fast!

What if someone told you, this snippet of just a class is already a fully working API:

    [Api("/courses")]
    public class Course : IObjectBase<int>
    {
        public int Id { get; set; }
        public List<Student> Students { get; set; }
        public Teacher Teacher { get; set; }
        public List<DateTime> Schedule { get; set; }
    }

Yes, this is the FULL code you have to write to get a working CRUD API with everything handled out of the box and working magically. Database, Routing, Caching, OpenAPI Definition...its all there, just based on this class.

The same can be done with pure JSON as well!

  {
    "name": "Car",
    "route": "/cars",
    "idType": "int",
    "Fields": [
      {
        "name": "Name",
        "type": "String"
      },
      {
        "name": "Description",
        "type": "String"
      },
      {
        "name": "Year",
        "type": "int"
      },
      {
        "name": "Make",
        "type": "virtual Make"
      },
      {
        "name": "MakeId",
        "type": "int"
      }
    ]
  }

How is this done? What is this magic?

Creating APIs that fast and simple can be done using my OS Project "APIGenerator". You can find it on Github here -> https://github.com/DeeJayTC/net-dynamic-api
A few more details can also be found here -> https://www.tcdev.de/instant-crud-apis-with-net

The APIGenerator basically turns any class or JSON Definition that follows my schema, into a full blown API with everything working out of the box.
It can be used with any Database supported by EntityFramework.

Getting Started

Start either a new WebAPI or WebApp project with .NET 6

Download the package:

dotnet add package TCDev.ApiGenerator

The APIGenerator comes with a few optional dependencies out of which you need to pick at least the database ones to use the API properly.

Install either of these for the matching database:

TCDev.APIGenerator.Data.SQL
TCDev.APIGenerator.Data.SQLite
TCDev.APIGenerator.Data.Postgres
TCDev.APIGenerator.Data.InMemory

And highly recommended to use the OData package as well

dotnet add package TCDev.APIGenerator.OData

Setting things up:

Add the library to program.cs (or startup.cs if you're using the old way!)

builder.Services.AddApiGeneratorServices()
                .AddConfig(NameOfRootNodeInAppSettings)
                or
                .AddConfig(new ApiGeneratorConfig() { ... })
                or
                .AddConfig()

Creating your first API

The first and most important thing to note is, you need to implement the "IObjectBase<T>" interface for your primary key. This is made to allow you to select the type of primary key (int, string or guid) you want to use but is also used to generate the API Endpoints later on. This is the minimum requirement you have to do.

Lets write a class as a sample:

public class Person : IObjectBase<int> {
public int Id {get;set;}
public string Name {get;set;}
public DateTime DateOfBirth {get;set;}
}

Now, this is enough for our underlying systems to generate the database tables for this specific class and you can theoretically query and store data for it. Yet this is not an API Endpoint yet.

To have a class appear in swagger and have all the needed CRUD endpoints generated you have to actually mark it as an API, this is quite easy thanks to our API Attribute.

Lets further extend the class to work as an API

[Api("/people")
public class Person : IObjectBase<int> {
public int Id {get;set;}
public string Name {get;set;}
public DateTime DateOfBirth {get;set;}
}

See how we only added that attribute? Yes, this is enough to turn the class into a full API! If you start your App now you should be greeted by Swagger with a fully working API!

For more details and guides just jump straight to the docs! ->

https://www.tcdev.de/

Let me know what you think, any questions..just jump in the comments below!

Generic controllers in .NET Core

2022-03-31T00:00:00Z

In many many repositories you can find tons of controllers, completely similar code with the only difference of serving different types.

Here's one approach to fix this. If you just want the full code, skip the article and look here -> https://github.com/DeeJayTC/samples

Using one generic controller for all the types in your project

First step is to create a generic controller, this is a really simple part, just implement a controller as usually and add T to make it generic.
We also need to add a common interface to all the classes, I just named it IObjectBase. This is used to make sure all classes share the same ID Property.

The Interface:

   public interface IObjectBase<TId>
   {
      [Key]
      TId Id { get; set; }
   }

The Controller:

[Route("api/[controller]")]
[Produces("application/json")]
public class GenericController<T> : Controller where T : class,
   IObjectBase
{
   private readonly GenericDbContext db;
public GenericController(GenericDbContext context)
{
this.db = context;
}
[HttpGet]
public IQueryable<T> Get()
{
return this.db.Set<T>();
}
....excluded for brevity, full sample in repo

We also add a DBContext pretty much as usually, similar to this:

public class GenericDbContext : DbContext
{
   public static IModel StaticModel { get; } = BuildStaticModel();
public DbSet<Something> Somethings { get; set; }
public DbSet<SomeOtherThing> OtherThing { get; set; }
protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
if (!optionsBuilder.IsConfigured) optionsBuilder.UseInMemoryDatabase("ApplicationDb");
}
protected override void OnModelCreating(ModelBuilder builder)
{
base.OnModelCreating(builder);
}
private static IModel BuildStaticModel()
{
using var dbContext = new GenericDbContext();
return dbContext.Model;
}
}

Don't forget to add the DBContext to your startup file!

Lets put things together

To tell .NET Core that we want to add additional controllers and routes we need to change the AddMVC call a bit

builder.Services.AddMvc(o =>
      o.Conventions.Add(new GenericControllerRouteConvention()))
       .ConfigureApplicationPartManager(m => m.FeatureProviders.Add(
          new GenericTypeControllerFeatureProvider(new[] {  Assembly.GetEntryAssembly().FullName}))
);

The ApplicationPartManager and FeatureProvider allows you to add new controllers at runtime ( See here )

In the feature provider we need to find a way to find all the classes we want to use as a controller, here we are again using our Interface. This can be done using a custom attribute or anything similar thats shared by all classes supposed to create a controller.

Here's a sample code for this:

   public void PopulateFeature(IEnumerable<ApplicationPart> parts, ControllerFeature feature)
   {
      foreach (var assembly in this.Assemblies)
      {
         var loadedAssembly = Assembly.Load(assembly);
         var customClasses = loadedAssembly.GetExportedTypes()
            .Where(x => x.IsAssignableTo(typeof(IObjectBase)) && x.Name != nameof(IObjectBase));
foreach (var candidate in customClasses)
{
// Ignore BaseController itself
if (candidate.FullName != null && candidate.FullName.Contains("BaseController")) continue;
// Generate type info for our runtime controller, assign class as T
var propertyType = candidate.GetProperty("Id")
?.PropertyType;
if (propertyType == null) continue;
var typeInfo = typeof(GenericController<,>).MakeGenericType(candidate, propertyType)
.GetTypeInfo();
// Finally add the new controller via FeatureProvider ->
feature.Controllers.Add(typeInfo);
}
}
}

Last but not least we need to make AttributeRouting work, this can be done quite easily as well, there's a function called IControllerModelConvention.
We can use this to apply route conventions to all GenericController instances.

   public void Apply(ControllerModel controller)
   {
      if (controller.ControllerType.IsGenericType)
      {
         var genericType = controller.ControllerType.GenericTypeArguments[0];
         controller.ControllerName = genericType.Name;
         controller.Selectors.Add(new SelectorModel
         {
            AttributeRouteModel = new AttributeRouteModel(new RouteAttribute($"/{genericType.Name}"))
         });
      }
   }

Final Words

Implementing things like this allows you to have a shared controller for all types that don't need any specific work done. You can still add a normal controller for special cases and everything else, swagger for example, keeps working as usually.

Just check the sample here -> https://github.com/DeeJayTC/samples/tree/main/GenericControllers

OpenSource is not free software!

2022-03-31T00:00:00Z

The last days, during MVP Summit (yay #MVPBuzz!) there where often topics covered related to OpenSource in many ways. And there was one line you could find in all of them: The problem with OpenSource developers and missing gratitude for their work.

These days, without open source, Github and all these lovely so to say "free" tools, many many startups wouldn't be where they are today. Yes even many bigger enterprises would probably struggle. Think alone how many devices, apps, real people where effected by the recent Log4J problem. Log4j is the de-facto default logging library in Java and was even ported, yet again as open source, by the community. With the recent bug it was actually easier to ask "Who is not affected" as it was just so many, theres millions using the library and if all of them would just give back $5! to the developers, there would be no issue at all fixing these bugs, maintaining libraries properly and so on. However, to my knowledge, theres very little companies that actually gave back something to the maintainers. IdentityServer 4, if you remember this was another similar story. The guys got some funding but by far not enough to pay their bills despite their work, again, being used by countless companies all around the world.

This and similar stories can be told for countless open source projects.

So lets have a look at things

Taken from Gartner, Worldwide IT spending is projected to total $4.2 trillion in 2021....yes trillion. Companies, private people, institutions, everyone pays a crazy amount of money for Software and Services. Its not that people don't pay for software, its the opposite. Crazy amounts of money are paid for pieces of software, sometimes built in a few hours and not even worth the money. Software development is pricey, reaaaally pricey if not to say expensive. If you look at the average saas product from start to finish and the amount of money it took you often end up with multiple 100k , sometimes millions.

When you look at startups, its even crazier. Some startups, wether they suceed or not, receive crazy funding from VC etc. Hasura just anounced they received $100M in funding. Thats not because someone is just throwing out money, no!. Thats because what they built actually has a value, worth and price tag! Building software is time consuming, takes a lot of effort, special skills and dedication.

When it comes to saas, apps, libraries...things you pay for. This is kinda the norm everyone knows about. Software has a price tag, i have to pay to use it, the guys spent money to implement it.
And don't even think about that every saas company is highly profitable. Many have less than 10% turnover, some even less than 5%. For many startups it takes years to actually be profitable!

After all, software has a price tag.

But open source is free? We can just use open source and don't have to pay or wait, its just sitting there for everyone to take!

Open Source is not free software!

Yes, you can use Open Source libraries and apps for free, if you look at this as simple as that. Yes, OS is free. However thats not even half the picture.

Think of it from another point of view: Open Source developers, project owners, maintainers...they all give away literal money for free!

On average these days, 1 hour freelance work is probably around 80-150€ some way above that some lower. Software agencies usually charge around 400-500 minimum per day. Yet OS people don't charge anything...they literarily donate, what in many many cases is their own free time, to the world. To me, many of them are heroes on their own. Without open source, many of theese agencies would have to charge easily double that if not more!

Very little companies value open source and allow their developers to work on projects during working hours, countless lines of codes in open source projects are written in the evenings, weekends and even on vacation. Just because someone is dedicated to built something. ( its actually 22:15 here while writing this! )

Many projects have one thing in common, they want to help. Help make other developer's live better, help sort of problem other's might have, help educate others and help other developers to grow and start a career in tech. By saying open source is free and by acting like many people do you completely devalue the effort, dedication and energy anyone working on open source brings to the table!

However, it does not have to be like this!

Just try to give back!!

Just think about, what was the last open source project you used. Which os libraries do you rely on for your saas product? Which sdk's really help you have an easier time at work? Which blog author, content creator or maintainer helped you solve an issue? And then think about how much time you would need if their work wouldn't exist. Think about, could you have built your saas app the way you did without open source? Just be nice, and kind and give at least something back.

Giving back to open source doesn't always have to be money, if you can't afford paying money there's other stuff you can do! Sometimes even sending a tweet "Hey we're using that awesome open source library xx" already helps. Helps raise awareness and maybe someone else can support them monetary.

If you can afford it, Github has a really great way to give back to developers, projects and maintainers.

Github Sponsors

GitHub Sponsors allows the developer community to financially support the people and organizations who design, build, and maintain the open source projects they depend on, directly on GitHub. That is, you can directly support all the projects, developers and communities you are building your own work on. And you should make use of this!

When you go to Github and visit the projects you're using in your product just have a look at the Sponsors button. You might see something like this in the navigation:

By using the sponsor functionality you can directly donate to the project owner and give back and just show you're actually valueing what they're doing. If the project you want to support doesn't have sponsoring enabled, just reach out to them kindly, tell them you want to support and ask them how you can donate. You can point them to this blog article if you want to: https://github.blog/2020-03-24-getting-started-with-github-sponsors/

If the project has the sponsor button but none of the tiers match what you want to give them, just kindly reach out and ask them to enable "custom funding". By doing that you can just pay whatever you like.

Final words

I know this is a topic countless people where writing about already but it also can't be said often enough. Start to value open source work, start to actually show you're grateful for what these awesome guys do and start support the projects you love. Now... i'll wait here..just go and sponsor someone!

Joke's aside... the open source community is important for every software company on this planet, its in our all responsibility that people keep publishing things, working on open source and even grow the community as otherwise things would become pretty tricky quite soon.

Greets...and go sponsor someone!

TCDev API Generator - Getting Started

2022-03-27T00:00:00Z

Hey Folks, as I received a few questions I decided to write a quick getting started guide ...and prolly should give that baby a proper name at some point!

The current state of the project will generate a fully working CRUD API from just a model class, eventually it will evolve in a full "Database direct to API" project similar to Hasura or other options.

You can find the docs....in desperate need of an update... here -> https://www.tcdev.de

Getting Started

Start either a new WebAPI or WebApp project with .NET 6

Download the package via nuget:

dotnet add package TCDev.ApiGenerator

Add the library to program.cs (or startup.cs if you're using the old way!)

builder.Services.AddApiGeneratorServices()
                .AddConfig(NameOfRootNodeInAppSettings)
                or
                .AddConfig(new ApiGeneratorConfig() { ... })
                or
                .AddConfig()

Note: Assembly.GetExecutingAssembly() can be overwritten, just use the assembly where you plan to add your models!

Optional Step: Migrations

When using SQLite or SQL you can have automatic migrations enabled, this is useful for development but shouldn't be used once you're done and especially not if you use an
existing Database!

app.UseApiGenerator();
app.UseAutomaticAPIMigrations(true);

Build your first API

Building your first API is as simple as just adding a class to your project, something along these lines:

   [Api("/people", ApiMethodsToGenerate.All )]
   public class Person :  IObjectBase<Guid>
   {
      public string Name { get; set; }
      public DateTime Date { get; set; }
      public string Description { get; set; }
      public int Age { get; set; }
      public Guid Id { get; set; }
}

The only requirement is that you have to use the IObjectBase<TEntityType> interface. This tells the library which type your primary key has and is used for various things. This requirement might change but the current versions require this.

To turn your class into an API just add the ApiAttribute as seen above and set the route to whatever you want it to be. (Needs to start with trailing / )
The second parameter controls which API Methods should be available.

Just start your project now and you'll be greeted by Swagger Docs showing you the docs for your API and you can start using it, it should already work :)

Configure the Database

Per default the project uses an InMemory Database Provider, good for development but probably you want to change that quickly. Nothing easier than that :9
Add this to your AppSettings:

  "Api": {
    "Database": {
      "DatabaseType": "SQL"
    }
  }

And additionally the connection string:

  "ConnectionStrings": {
    "ApiGeneratorDatabase": "Server=localhost;database=tcdev_dev_222;user=sa;password=Password!23;"
  },

Make sure the name is "ApiGeneratorDatabase" as this is a requirement right now.

If you start your project again it should now use your database and should have it automatically created.

If you want to have migrations automatically applied just add this to startup:

app.UseApiGenerator();
app.UseAutomaticAPIMigrations(true);

This is first of all everything you "have" to do...but theres more you can do

Configure your api even further

The lib comes with 2 helper classes you can use to have things cleaner. "Trackable" and "SoftDeletable".

Trackable adds two new fields to the database "CreatedAt" and "UpdatedAt" and handles everything automatically.
SoftDeletable does probably what you think it does, items are not deleted but just "marked" as deleted

Customize behaviour

You can add various interfaces to your class to inject custom functionality, currently called Hooks. For every method theres a Before and After Hook, similar to this:

   [Api("/people", ApiMethodsToGenerate.All )]
   public class Person : Trackable, 
      IObjectBase<Guid>,
      IBeforeUpdate<Person>, // Before Update Hook
      IBeforeDelete<Person>, // BeforeDelete Hook
{

Implementing the interface allows you to intercept whats happening and add custom functionality, like in this example:

      public Task<Person> BeforeUpdate(Person newPerson, Person oldPerson)
      {
         newPerson.Age = 333;
return Task.FromResult(newPerson);
}

..more to come

Last but not least, customize database layout

To customize the table and how your model looks in the database you can use classic EntityFramework functionality.
Just add the IEntityTypeConfiguration interface and you can use all the EntityFramework options like here:

   [Api("/people", ApiMethodsToGenerate.All )]
   public class Person : Trackable, 
      IObjectBase<Guid>,
      IEntityTypeConfiguration<Person> // Configure Table Options yourself
   {
      public void Configure(EntityTypeBuilder<Person> builder)
      {
         builder.ToTable("MyFancyTableName");
         //....all the other EF Core Options
      }

way more to come....add issues and discussions to github! See you soon

Be the one who wrote the posts and gave the talks!

2022-03-26T00:00:00Z

Hey visitor,
this is something, not about code as such but something I realized about myself the last months and pretty sure there's more of you who think similar.

I've written countless lines of codes, caused countless bugs, fixed them, caused new ones but all that ends up as experience. Some people ask "how do you know so much?" and the only answer is
try and error, practice and just never stop learning. However, you can only learn if there's actually people around to share their experience with you. Yes, you can learn everything the hard way yourself but many many people wouldn't work in tech todays if it wasn't for great tutorials, tutors and just an epic community all around the world.

There are people, constantly trying to help other developers some really famous and some below the radar but still doing what they can.

I planned to write about this quite a while ago but just now had the missing inspiration I needed.

Scott Hanselmann who's pretty much the most famous face of Microsoft Development published a video on TikTok. While on its own its a great advice for many people and definitely worth a watch, its the final quote of the video I liked most about it which is something I thought for quite a long while. Watch it here -> Scott @ TikTok

He finished the video with this quote:

"At the end of your career you don't want to be the one who read all the books, seen all the talks and used all the libraries. You wanna be the person who wrote the books, wrote the libraries and gave the talks"

So, whats so great about that?

I have a whole career in development, probably a bit more than 20 years to go and I thought about how to spend these years to actually create something valuable. Working on code is something thats great, enjoyable and what i'd definitely continue to do but I'm just not the typical developer anymore. I don't enjoy coding 8 hours straight for a customer, I've done that and enjoyed it but realized there has to be more i can do.

Working in tech, for your employer, your own projects and whatever else is after all one thing, experience. Errors you made, problems you fixed and yes success you had finishing that project. Theres a never ending stream of new folks joining tech and while they often can code properly, build great things they all lack experience. A 20 year old guy might be an amazing programmer but he just doesn't have a ton of experience about what can go wrong and what to look for.

At some point in my career I realized that helping other developers is actually a lot more enjoyable than working on code myself. For various reasons. First of all, helping as such is already great. Making someone's life easier is great but you're also creating way more value than by writing code yourself. Second, the feeling of getting something done or having achieved something is way stronger when you wrote a library compared to just a finished project for the next customer or the next....

So, if you're the one who gave the talk, it only took you about an hour, maybe a few hours to prepare but thats it. What you created by doing that is to actually multiply your own experience, and based on that helped to create way more things than you'd ever be able to by just coding. Plus you made other people's work day a bit more enjoyable!

Lets dig a bit deeper

If you read a lot of books, use great libraries and watch all the sessions you can watch you're probably a pretty good developer and especially in my mid 20s thats what I did to learn, practice and enhance my skills. Thats what everyone does and thats really great. However, there have to be people to actually create libraries, books and talks as otherwise there won't be content left at some point and young fellas wouldn't be able to get running.

At some point in your career you need to think about what YOU can do for your community, how you can actually multiply your experience, help others to learn from your career, help them to accept making their own mistakes and to properly learn.

Time is the most precious resource we have.

Time is something you can't increase. You can hire 10 devs but you can't get 10 additional hours. So, lets take a look at a small example to explain this.
Lets say it takes you 10 hours to build something, it also takes 10 hours to prepare a blog post and small library for this. Now if we think of this, when you work
on the project you finish it, you have a project finished and done. Thats great, nothing bad about this.

Now if you would have spend the same time to build a library or write a blog post you might not have finished the project BUT you actually did way more than that, you've enabled
other developers to do what you can do. And by that, instead of finishing that one project you helped finish countless other projects as well.

10 hours spent writing on a book might help 1000 other developers get their job done faster and easier and you actually achieved way more than you would have by just consuming and coding yourself.

Be the one who wrote the books, gave the talks and built the libraries

That said, at some point in your career you have to decide if you want to actually just quit with 65, having built a couple of possibly great projects but thats about it or if you actually enabled other developers to continue, grow and build even more projects you helped them to build.

If you're the one who wrote the books, gave the talks and built the libraries you have way more to look back at the end of your career. You'll be a lot more satisfied with what you achieved and you actually left way more in the community than you whould have by just writing code.

Code is getting old will probably be thrown away at some point and all you did is gone a few years later. If you, however, enabled other developers to become better in their job your work will probably be great years after you finished your career.

You're not good at writing or talking?

You might not enjoy talking in front of people, your writing skills might not be perfect...who cares? Mine aren't but its all about the content. As long as people can understand the point you're trying to make or understand the content you want to deliver its definitely good enough and worth to share. Don't be afraid..just start sharing! You probably can't do everything anyway, some people help by wiriting great libraries, they don't want to talk publicaly but thats totally fine, you're still helping other.

So all thats left to say... think about how you can help other developers, what you learned in your career you want to share. Everything you know can possibly help other developers so just start writing and don't be afraid to make mistakes doing that. You will make mistakes...you will learn from them and you will tell others about the problems you had. Thats a really great thing!

So..what are you waiting for, go and get some stuff written down!

Also:

Thanks Scott :)

The new TCDev

2022-03-25T00:00:00Z

Welcome to the new TCDev.de!

My page was offline for quite some time and desperately needed an update. I thought i'd do something new this time, something i didn't try yet. My community page https://www.madewithcards.io was up and running for quite a while, the internal blog module however was a bit of a mess and really needed to be replaced. I figured I did not want a seperate blog module for both pages and I also didn't want to use Wordpress or anything similar. So i decided to give ButterCMS a try, as a headless cms was pretty much what i needed to achieve what i wanted. A shared blog between both pages with the features i wanted to have.

The new TCDev.de is built with

Vue + Vuetify (V2 as Vuetify isn't completely supported on V3 yet!)
ButterCMS for content
Github + Cloudflare Pages for hosting
Prerender.io for SEO improvements
.NET Core WebAPI for some API things I'm not talking about yet :)

First of all, what is ButterCMS? What is a headless CMS?

ButterCMS is an API-based or “headless” CMS, technically its a content management system as you might know it, Wordpress etc. However its fully API based. Headless here means, there's no "Head" aka Frontend for the CMS. Everything you do is purely accessible by using their API. In my case, exactly as i wanted. And a big plus.... ButterCMS has a free non-profit offering, you have to ask them for it and have to share a backlink on your page but hey, thats grant for awesome free functionality like this!

Starting with ButterCMS is quick and easy, sign up, take your API key, install the Vue SDK and you're pretty much done, the onboarding flow already gives you the first snippet you can use directly in the framework you're working with. Yes the guys give you snippets exactly for what you're using, they offer tons of Frameworks to chose from:

In my case i'm working with Vue. Getting started with ButterCMS takes seconds really. By just following the onboarding guide you already have a working blog. For me things where a bit different. I wanted more than a normal blog.

Blog posts with references and further links.

For the blog I had in mind i wanted to be able to have a section in the sidepane linking tech pieces used in the post. For example, when writing about Vue or AdaptiveCards i wanted to link these in the resources section. ButterCMS can do that pretty well with references, however these don't exist on the pre-made blog pages. Luckily you can add custom pages types which perfectly did the trick for me. Read more about custom page types here. Blog posts in ButterCMS are technically the same as the custom pages, its just a pre-made page type that pretty much resembled the blog post type and additionally added the fields I needed.

In my new "CustomBlog" page type I added a few references such as "Stack", "Category", "External Author" and a few more. These references are just custom collection types, another feature of ButterCMS. Think of it like custom collections where you define the fields, add items and use these in your posts and pages. As simple as that.

After all, despite needing a custom setup, things where still quick and smooth in ButterCMS. The UI is really handy, you never feel lost and setting it all up was done quickly.

Sharing a blog between two pages

As said before, I wanted to share the blog between both my MadeWithCards page and TCDev.de. Luckily as both are Vue pages I only had to write the template once and share it with both sources. There's only one difference. MadeWithCards is supposed to only show content either tagged with AdaptiveCards or in the AdaptiveCards category i added earlier. Thanks again to the lovely ButterCMS sdk this was also a matter of seconds to implement.
This is the code i'm using to fetch my posts, after fetching I group the posts by year for display purposes.

     
     butter.page
        .list('customblog',params)
        .then((res) => {
          const postGroups = []
res.data.data.forEach((post) => {
const group = postGroups.find((x) => x.name === moment(post.fields.published).format('yyyy'))
if (!group) postGroups.push({
name: moment(post.fields.published).format('yyyy'),
posts: [post]
})
else group.posts.push(post)
})
this.posts = postGroups.sort((p) => p.name).reverse()
})

The only thing thats different on MadeWithCards is the "params" part.

While TCDev is using these params:

      const params = {
        page: 1,
        page_size: 25,
        exclude_body: true,
        'filter.tags.slug': this.currentTag
      }

which is using a custom tag filter based on the currently selected tags on the page, MadeWithCards has the tags and category hardcoded:

      const params = {
        page: 1,
        page_size: 25,
        exclude_body: true,
        'filter.tags.slug': 'adaptive-cards',
        'filter.category.slug': 'adaptive-cards',
      }

As you can see in these two examples, the formentioned collections and all other fields I manually added to my page type are all filter and sortable!

Custom "Preview" protection

With ButterCMS you can easily preview your page while you're working on it and see it in your own page. Butter has a nice functionality for this. For me this wasn't enough. ButterCMS just applies a "preview=1" parameter and you're supposed to check this in your code and then display the preview. I wanted a way that at least is a bit more complex.

My custom blog page type has a field "preview-code" which is just a random number. When previewing the page the "&preview" param must match whats returned from ButterCMS API, otherwise the page can not be previewed. While this is not perfect its still good enough for me.

Including "external" posts

From time to time I want to add references to posts from other author's especially on MadeWithCards. I don't want to copy their content into a new post but also don't want to use any RSS feed as I want to pick manually which posts to add. Achieving this for me was pretty fast, again due to ButterCMS.

My custom blog type has 2 fields "isExternal" and "externalUrl" besides the reference to an author. Whenever i have an external post I add a new post, leave it completely empty and just fill out the title and externalXX fields besides adding a preview image maybe. By doing this I can render external and "internal" posts differently in Vue. While my own posts have a dedicated page to show the content and details, external posts are opened in a new tab using the externalUrl. Viewers can identify wether its my own or a shared post by checking the author and a huge "external" banner on the images.

Getting the page deployed and hosted.

I wanted to keep things as simple as I can, no hussle with any sort of webserver or cloud hosting. Just my static Vue page with the dynamic content from ButterCMS. Luckily there's a really easy way to do this. Github and Cloudflare Pages

Cloudflare Pages pretty much takes your Github code, deploys it to one of their servers and gives you a URL for it. Fully automatic and setup only takes a couple minutes. After the first deploy, every commit to the selected branch automatically re-deploys your code. Ci/CD made simple :)

I won't go into the details here as the documentation is already pretty good, just give it a read!

Improving SEO

As you might know, SPA's are a bit tricky when it comes to crawlers. Most of the content requires javascript to be executed and the page fully rendered to appear. There's various ways to achieve this. Server side rendering, Pre-rendered for crawlers and more. I decided to go the pre rendered route but instead of doing all of this myself I chose to use PrerenderIo. Its free for a set amount of cached pages and also plays nicely with Cloudflare using a Worker. Using Cloudflare with Prerender.io

With all this in place I was done for now and have my new page online, rest is adding content which I'll add tons more.

Stay tuned!

#SharingIsCaring!

2022-03-18T00:00:00Z

#SharingIsCaring and #SharingFeelsGood....

The last few days i uploaded various things to Github, mostly older stuff but also pretty new unfinished work in progress things.
While cleaning up my harddrive i decided that it doesn't help when the code is just flying around on my end. I needed to back it up anyway,
a public github repo is great place to back up code...its secure and also helps other people :)

https://github.com/DeeJayTC/dotnet-utils

Is a collection of various things, extension methods, useful functions, other stuff i collected through the years. Taken from various older repositories,
some new stuff. Made available with no license at all. Just take whatever you want, leaving a star would be great tho :)

https://github.com/DeeJayTC/cloudstorage-wrapper

Is a microservice i made while working for Teamwork, still being used for integrations today. It basically wraps the Dropbox, Onedrive and Sharepoint API's and makes it available
under one common API schema. If you're a SAAS app and want to build an integration with either, this is for you...you only have to do things once and can
support all three. I might add Google Drive and Box.com at some point.

https://github.com/DeeJayTC/net-dynamic-api

Is just a pet project but might be useful for some once its more evolved.

It basically turns this:

Into a fully working CRUD API with ODATA enabled

Feel free to browse and use the stuff, leave a comment if you can!

Instant CRUD APIs with .NET

2022-03-10T00:00:00Z

These days there's a rising demand to reduce boilerplate code in apps, more and more tools are appearing reducing backend code even further, such as Hasura's automatic creation of GraphQL APIs.
Here's a somewhat different approach to this.

What if someone says that this is the full code needed for a fully working CRUD API with ODATA filter options enabled?

   [GeneratedController("/people")]
   public class Person : Trackable, IObjectBase<Guid>
   {
      public string Name { get; set; }
      public DateTime Date { get; set; }
      public string Description { get; set; }
      public int Age { get; set; }
public IEnumerable<PersonLink> Links { get; set; }
public Guid Id { get; set; }
}

Sounds a bit crazy but yea, its already done and availble...sort of. There's no Nuget package yet but you can go to Github and grab the code if you want to.
An API created like this has everything done automatically, all CRUD Endpoints, fully routing, even Authorization is working. Besides various things like caching and even webhooks once implemented.
A lot of this is still in early alpha tho.

The class will generate these routes:

Method	Endpoint
GET	/people
GET	/people/{id]
POST	/people
DELETE	/people/{id}

Besides that you'll have the known ODATA filter options like $filter, $select etc

But lets tell you a bit about how this is done.

The whole API Generator is built with EntityFramework Core, .Net Core and the Microsoft ODATA Libraries. Thats pretty much it.
The first step to achieve what I wanted to is to get the EFCore pieces done, have the DBContext generated at runtime fully working with all possible options available.

After digging a bit into things I figured that this is actually quite easy.
EntityFramework offers various ways to generate the DBContext and DBSchema. You're probably familiar with the usual OnModelCreating and ModelBuilder approaches.
Something like this:

      protected override void OnModelCreating(ModelBuilder builder)
      {
         builder.Entity<Person>().HasKey("ID");
         base.OnModelCreating(builder);
      }

In my case, I don't know any of the classes at design time as the code is not in my library but in the code of whoever uses my tools. I needed a different approach. Luckily EntityFramework offers two really nice options here.

ApplyConfigurationsFromAssembly
- Allows you to extract the builder code and OnModelCreating into any class implementing IEntityTypeConfiguration
builder.Entity(type)
- Allows you to add an entity to the builder of any type, with reflection we can extract types from the calling assembly and use these here

By using these two options i was able to rewrite OnModelCreating to this:

      protected override void OnModelCreating(ModelBuilder builder)
      {
         // Add all types T using IEntityTypeConfiguration
         builder.ApplyConfigurationsFromAssembly(Assembly.GetEntryAssembly());
// Add all other types (auto mode)
var customTypes = Assembly.GetEntryAssembly().GetExportedTypes()
.Where(x => x.GetCustomAttributes<GeneratedControllerAttribute>().Any());
foreach (var customType in customTypes.Where(x => x.GetInterface("IEntityTypeConfiguration`1") == null))
builder.Entity(customType);
base.OnModelCreating(builder);
}

So what are we doing here?
We first of all take all Types implementing IEntityTypeConfiguration and apply their EntityConfiguration. Whatever class is using this only needs to implement the "Configure" function.

        public void Configure(EntityTypeBuilder<Person> builder)
        {
           //default stuff if nothing special
        }

This gets called from the OnModelCreating function and gets handled automatically by EntityFramework. When you work normally with EntityFramework you often don't want to configure the entities yourself and just let EF do its magic, this is also possible just a bit more tricky. By using reflection we want to grab all types that do NOT implement IEntityTypeConfiguration and just add them to EFCore. This is what happens here:

         // Add all other types (auto mode)
         var customTypes = Assembly.GetEntryAssembly().GetExportedTypes()
            .Where(x => x.GetCustomAttributes<GeneratedControllerAttribute>().Any());
         foreach (var customType in customTypes.Where(x => x.GetInterface("IEntityTypeConfiguration`1") == null))
            builder.Entity(customType);

You might see, theres a clause limiting the types to all types with a "GeneratedControllerAttribute" this is what my library uses to idenfity the actual classes used, otherwise we where not able to limit the results just to the classes we really want. The GeneratedControllerAttribute is further used to configure the output of the generated API, here's the definition:

      /// <summary>
      ///    Attribute defining auto generated controller for the class
      /// </summary>
      /// <param name="route">The full base route for the class ie /myclass/ </param>
      /// <param name="requiredReadClaims"></param>
      /// <param name="requiredWriteClaims"></param>
      /// <param name="requiredRolesRead"></param>
      /// <param name="requiredRolesWrite"></param>
      /// <param name="fireEvents"></param>
      /// <param name="authorize"></param>
      /// <param name="cache"></param>
      /// <param name="cacheDuration"></param>
      public GeneratedControllerAttribute(
         string route,
         string[] requiredReadClaims = null,
         string[] requiredWriteClaims = null,
         string[] requiredRolesRead = null,
         string[] requiredRolesWrite = null,
         bool fireEvents = false,
         bool authorize = true,
         bool cache = false,
         int cacheDuration = 50000)
      {

Once i was able to find all the types i wanted to use, it was just a matter of adding these as entities to EFCore. Thats about the DBContext part.
The rest that was needed was actually far easier than i expected, using dependency injection and generic types.

I created two classes, a generic repository and a generic controller

   public interface IGenericRespository<T, TEntityId> : IDisposable
   {
      IQueryable<T> Get();
T Get(TEntityId id);
Task<T> GetAsync(TEntityId id);
void Create(T record);
void Update(T record);
void Delete(TEntityId id);
int Save();
Task<int> SaveAsync();
}

Accessing the data in EF is rather simple, here's the Get implementation:

      public TEntity Get(TEntityId id)
      {
         return Get().SingleOrDefault(e => e.Id.ToString() == id.ToString());
      }

Posting the full controller here is quite long so i'll only post the ctor and class as such:

   [Route("api/[controller]")]
   [Produces("application/json")]
   public class GenericController<T, TEntityId> : ODataController
      where T : class,
      IObjectBase<TEntityId>
   {
      public GenericController(IAuthorizationService authorizationService, IGenericRespository<T, TEntityId> repository)
      {
         _repository = repository;
         _authorizationService = authorizationService;
ConfigureController();
}

What the hell does IObjectBase<TEntityId> actually do here?

For many things in here you need to know what the primary key of the class is, EntityFramework needs it and the controller as well. As i wanted to allow people to use whatever type they want to use I added a simple interface:

   public interface IObjectBase<TId>
   {
      [Key]
      [DatabaseGenerated(DatabaseGeneratedOption.Identity)]
      TId Id { get; set; }
   }

By using this people can choose whatever primary key (string, int or guid) they want to have and i know what the type is and have an easier time actually using it.

Putting it all together

So now that we have all the moving parts or at least the basics, we need to actually put things together. How can we actually use our generic controller? This is where .NET Core Application Parts and Feature Provider comes in, read more here

By writing our own ApplicationPart we can easily do what we're trying to achieve. I wrote an extension method to IMVCBuilder to initialize everything during app startup. Yes, right now it only works during startup and not fully dynamic but thats step2.

For initialization you need to pass your feature provider to the AddMvc method, similar to this:

         services.AddMvc(o => 
               o.Conventions.Add(new GenericControllerRouteConvention()))
                  .ConfigureApplicationPartManager(m =>
                     m.FeatureProviders.Add(new GenericTypeControllerFeatureProvider(new[] {assembly.FullName}))

The GenericControllerRouteConvention is one of the main part to allow the routing engine to work for dynamically generated controllers. While we only have one "Generic Controller" instances are getting added for each type we have added to the app. And the router needs to know which route the controller is listening to. This is how the RouteConvention looks right now and again we're using our GeneratedControllerAttribute here to configure the routing behaviour, controller name etc. This is important as this part is later also used by the Swagger implementation to create the OpenAPI Spec.

      public void Apply(ControllerModel controller)
      {
         if (controller.ControllerType.IsGenericType)
         {
            var genericType = controller.ControllerType.GenericTypeArguments[0];
            var customNameAttribute = genericType.GetCustomAttribute<GeneratedControllerAttribute>();
            controller.ControllerName = genericType.Name;
if (customNameAttribute?.Route != null)
{
if (controller.Selectors.Count > 0)
{
var currentSelector = controller.Selectors[0];
currentSelector.AttributeRouteModel = new AttributeRouteModel(new RouteAttribute(customNameAttribute.Route));
}
else
{
controller.Selectors.Add(new SelectorModel
{
AttributeRouteModel = new AttributeRouteModel(new RouteAttribute(customNameAttribute.Route))
});
}
}
}
}

The RouteConvention is not the only part, the second part is the actual FeatureProvider I had to implement. The provider is the magic part that actually goes through the assembly, fetches the types with our attribute and adds a controller "feature" for each. (note: we excluded BaseController here as thats our generic one we don't need twice)

      public void PopulateFeature(IEnumerable<ApplicationPart> parts, ControllerFeature feature)
      {
         foreach (var assembly in Assemblies)
         {
            var loadedAssembly = Assembly.Load(assembly);
            var customClasses = loadedAssembly.GetExportedTypes().Where(x => x.GetCustomAttributes<GeneratedControllerAttribute>().Any());
foreach (var candidate in customClasses)
{
// Ignore BaseController itself
if (candidate.FullName != null && candidate.FullName.Contains("BaseController")) continue;
// Generate type info for our runtime controller, assign class as T
var propertyType = candidate.GetProperty("Id")?.PropertyType;
if (propertyType == null) continue;
var typeInfo = typeof(GenericController<,>).MakeGenericType(candidate, propertyType).GetTypeInfo();
// Finally add the new controller via FeatureProvider ->
feature.Controllers.Add(typeInfo);
}
}
}

And thats about it first of all, having all these parts combined and added you'd now get an already working API when running the app.
You can find a small sample app demonstrating the functionality here: https://github.com/DeeJayTC/net-dynamic-api/tree/main/sample/ApiGeneratorSampleApp

MadeWithCards Updates February 22

2022-02-15T00:00:00Z

New Updates and even more content!

Since quite a while I didn't do any updates to the page, the blog was literarily not existing and we only had community calls from the Adaptive Cards Team as such.
This changes now! MadeWithCards was always about content related to Adaptive Cards. While the getting started sections and cards as such where really helpfull already, the blog and media sections where severely lacking. From now on I'll frequently add new video's and blog posts from the community. You'll find a lot more content on the page.

The new "Media" Channel

Our new Media area now not only lists Adaptive Cards Community calls but all Community Calls with Adaptive Cards related content. I also added already and will continue to add videos and guides made by the community. This is first of all a community project so ..more community content for you guys!

The "new" Blog

Besides having my own articles as before, the blog now will become a huge collection of blog posts, guides, news and updates from various community members. This is hand picked first of all to keep a specific quality level. If you want your posts to be added here, join the community discord and let me know or send a mail to tim@madewithcards.io.

I'll continue adding new posts as i see them, coming back frequently now makes a lot more sense for you guys!

Join the community discord!

As a small Idea to try out I created a Discord Server "MadeWithCards" Join here!

I've heard a couple of times that its quite hard to find people when it comes to helping with Adaptive Cards. Yes you can read all the posts, watch the videos but sometimes you have a specific question. Stackoverflow is already a good source but sometimes you want a more detailed or direct answer. Thats the idea behind the discord server.

Discord has a lot lower entry barrier compared to like the AdaptiveCards TAP and is free to join for everyone.

Lets try and create a nice and lovely community here!

A note at the end

EVERYTHING i do, this page, the AdaptiveCards Studio extension, my libraries and everything is and will always be completely free, no fee's nothing and no adds on any of my websites. Won't happen...never! That said, if you really like to and think my work is worth a few bucks consider using Github Sponsors here . You obviously don't have to...but hey, if you want to, much appreciated and I'll make sure to list you as a sponsor on the page!

Greetings
Tim

.NET App Settings explained

2021-11-25T00:00:00Z

In the last days I often saw questions related to appsettings. Thats something many people still have concerns about or are unsure how to handle things properly.
This is my approach to do that

Lets try to walk through it:

This is a piece of code i usually have in my apps responsible for loading your app configuration.

Configuration = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json")
    .AddJsonFile($"appsettings.{env.Name}.json")
    .AddJsonFile("secrets.json")
    .AddAzureKeyVault() <-- should be here
    .AddEnvironmentVariables() < --should alwas be the last
    .Build();

The first two parts are pretty self explainatory, you just tell your app where to look for the files so you don't have to use long paths. In this case we say that all json files are in "CurrentDirectory" which is the base directory of your app.

AddJsonFile("appsettings.json")
appsettings.json should always only include settings that are valid for all app instances, no matter if development or production.
This is where you put generic settings, something that applies to every developer and all people working with your code.
AddJsonFIle("appsettings.{env.Name}.json")
This is where some of the magic of configuration happens, you might have noticed that you have more than one app settings file in your app.
Usually something like this:
"appsettings.development.json"
"appsettings.production.json"
"appsettings.staging.json"
these files get loaded depending on the environment you're currently in and override the prior loaded config if there's matching keys.

Lets say you have this in your appsettings.json
```
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
```
These are general settings that should apply if not overwritten anywhere else. Now, in the development settings we could have something like this:
```
  "Logging": {
    "LogLevel": {
      "Default": "Verbose",
    }
  }
```
This would mean that while you're in development , the log settings are way more verbose and you overwrite the normal app settings by doing this.

Have in mind that this only works because the order of loading configuration files is important. Each key gets overwritten by the same key if loaded later.
Thats also why Environmental variables should come last, but we'll get to this.
AddJsonFile("secrets.json")
The secrets.json is what i usually use to store local development secrets, nothing too private but also something that might be personal per developer. Best is to not include this file in your repository and just add it to .gitignore. This is where your devs can add their own settings which should not collide with anyone else.

AddAzureKeyVault
The AzureKeyVault is where usually private keys, settings, url's and otherwise confidential stuff can be stored for your production apps. Usually you don't have a key vault locally and this setting only applies to production. As this comes late in the chain it will overide all prior app settings. When hosting an app on azure you should use this for client secrets, client ids, database connection strings and whatever else should be secret

Here's a guide taken from Microsoft Docs
AddEnvironmentalVariables()
The last bit in the picture are environmental variables, you might see it differently but in my case i always want the env vars to override everything else, mostly for containerization reasons. Env vars are whats primary used to configure applications inside Docker. But Helm Charts and Kubernetes also play a big role here. When deploying containers you often work with deployment scripts and set things on a more global level, really often using environmental vars in like docker-compose files.

It happened often in past that the settings did not have any effect leading to confusion because some appsetting was overwriting the environmental variables. Thats why I decided that these are always loaded last to make sure that If there is a specific environment variable its the setting that is in effect and beats all the others.

A word on Github Repositories and Settings

If you ask whats actually suposed to be pushed in the source the answer is quite simple and easy.

Don't push:
- Anything thats containing private keys, otherwise confidential data (like secrets.json, docker-compose files with secrets in it...anything similar)
- Anything thats for a specific person, ie personal developer settings
Do push:
- The default appsettings.json
- Anything that only contains app configuration like logging settings or url's you don't have to keep secret
- Anything noone can do any harm with.

The new MadeWithCards.io

2021-09-15T00:00:00Z

Hey Everyone! We're back in new shape, better than ever! :)

As you might have noticed, you're reading this on a brand new page :) Our old page was build pretty fast and lacked some substantial features we needed to improve it and add new features. So we had to rebuild quite a few things from scratch. This took quite a while to acomplish and you did not hear from us in a while...this is done now :)

We now have a brand new www.madewithcards.io page, lots of features to be added soon. While there still is some stuff left to work on, we didn't want to wait any longer and show the community our work. There's some tuning to do, our blog isn't finished yet and various features behind the scenes need some love aswell but its by far better than the old page and there's a bunch of stuff already available!

There's a ton of new features added and to be added soon

Customize the page :)

A more gimicky feature but you can now decide if you want the page in light or dark...just use the cogs icon on the right to chose. You can also change the default card layout from here.

A brand new getting started section!

We extended the page with a brand new getting started section, this is getting filled more and more and will help people getting started with AdaptiveCards. We list Microsoft Learn content, recommended blog posts besides various documentation link to help you find what you need!
Starting with AdaptiveCards was never easier ;)

Our brand new AdaptiveCards API!

The old page had the cards sort of hardcoded in the page's own database, the new MadeWithCards.io is using our public Cards Database. Yea, right you can get all the cards on the page, and all cards we'll add via https://api.madewithcards.io. This also means that in future, all public cards can be used in BotFramework, VSCode or your Power Automate flows making shared cards even more useful for the community.

While the API is already online, it can only be used for selected user's at the moment. We plan to have the API commonly available soon.

A note on cards: currently not all the old cards are online on the page, this is because we're transistioning to the new system. You will find all cards and a bunch of new cards soon in the cards section.

Your own cards!

Once our API is publicly available you will also be online to login to the page, add your own cards (even private!) make your own cards public and edit your cards from VSCode or the Designer. THis will allow you to re-use cards everywhere you like to from PowerAutomate to Teams Apps and more. Yes even Cards for SAP or Cisco.

With the help of the community we plan to have a huge section of AdaptiveCard templates for common data, such as Github.com or Asana, Teamwork, Wrike, Microsoft Graph API's and a lot more. We're always looking for Cards for "public" APIs. Any template build for data for any SAAS product really.

Various Extensions and Libraries

Easily use one of our cards from PowerAutomate, use cards from the API within Botframework and self contained cards using Stencil...this is just a few of things we're about to release pretty soon.

Oh...did you know you can embed AdaptiveCards in Medium.com blog posts soon? :)

AdaptiveCards Studio!

AdaptiveCards Studio will receive quite a few updates aswell, besides loading and editing cards directly from within VSCode you can also write cards in Yaml format and convert to JSON later. (Thanks to our friends at https://www.asseco.com)

Now...why all this?!

AdaptiveCards are reusable, templated and can easily be loaded from any source. We see quite a few people still hardcode cards in c# or botframework and want to help ease AdaptiveCards development and help people make their cards reusable, shareable and future proof :)

Want to know more? Leave us a message!

Stay tuned!

Tim

AC Templating is a game changer!

2021-07-01T00:00:00Z

Why templating for Adaptive Cards is a game-changer.

If you never heard of what Adaptive Cards are, it might be a good idea to learn a few things about them before we continue. Also on a separate note, some of the things covered in this post are what we’ve been talking about in the Microsoft Ignite session just recently.

If you prefer watching the session before reading, you can watch the recording here https://myignite.techcommunity.microsoft.com/sessions/81641

Adaptive Cards

Adaptive Cards are platform-agnostic snippets of UI, authored in JSON, that apps and services can openly exchange. When delivered to a specific app, the JSON is transformed into a native UI that automatically adapts to its surroundings. Cards are supported by various Microsoft products but are rendered anywhere you like even in your own apps.

Adaptive Card Templating

After talking about what Adaptive Cards are, let’s talk about the main topic of this post.

Templating. What is that all about?
Simply explained templating is data-binding onto JSON strings. It’s not even Adaptive Cards related as such it just lets you bind any data, be it JSON formatted or a specific object instance onto your JSON string. Yet similar to what a string replace would do just way more reliable and convenient with support for functions and arrays.

Basic data binding
Within your JSON file you can use placeholders like {person.firstName} or even access multiple levels with like {person.address.streeet} or {person.contact[2].phone}. The templating library is capable of running functions over your data, can repeat JSON structures based on arrays and a few more things.

You can easily access your data using these placeholders to start with:

{
 "{<property>}": "Implicitly binds to `$data.<property>`",
 "$data": "The current data object",
 "$root": "The root data object.",
 "$index": "The current index when iterating",
 "$host": "Access properties of the host *(not working yet)*"
}

Iterations and Conditions
All this gets even more interesting when we add iterations and conditions to the plate. Let us admit we have the following data returned from any API or database

{
 "title": "My list of people:",
 "count": 4,
 "people": [{
   "firstName": "Micky",
   "lastName": "Mouse",
   "age": 44
  },
  {
   "firstName": "Donald",
   "lastName": "Duck",
   "age": 12
  },
  {
   "firstName": "Harry",
   "lastName": "Potter",
   "age": 18
  },
  {
   "firstName": "Matt",
   "lastName": "Hidinger",
   "age": "28"
  }
 ]
}

Now we want to bind this onto the following JSON template:

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "TextBlock",
            "size": "Medium",
            "weight": "Bolder",
            "text": "{title}"
        },
        {
            "type": "FactSet",
            "facts": [
                {
                  "$data": "{people}",
                  "$when": "{$index.age > 12}",
                  "title": "{$index.firstName} {$index.lastName}",
                  "value": "{$index.age}"
                }
            ]
        }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0"
}

As you can see we access the properties from the data like the title but also firstName and lastName from the people’s array. the $when condition makes sure we only render people who are older than 12.
After transforming the data the resulting JSON will be this:

{
 "type": "AdaptiveCard",
 "body": [{
   "type": "TextBlock",
   "size": "Medium",
   "weight": "Bolder",
   "text": "My list of people"
  },
  {
   "type": "FactSet",
   "facts": [{
     "title": "Micky Mouse",
     "value": "44"
    },
    {
     "title": "Harry Potter",
     "value": "18"
    },
    {
     "title": "Matt Hidinger",
     "value": "28"
    }
   ]
  }
 ],
 "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
 "version": "1.0"
}

The transformation ignored Donald because his age is not above 12. But it repeatedly added facts for each of the people with condition met.

The final adaptive card would look like this:

Finally transformed and rendered card.

These are just examples, there’s a lot more you can do.
You can find all the available functionality here:
https://docs.microsoft.com/en-us/adaptive-cards/templating/
and
https://docs.microsoft.com/en-us/adaptive-cards/templating/language

Why is that useful now?

Think about how you usually generate JSON to send to any API or how you would normally generate JSON output for your own API. Most likely you have things like classes and serialization in mind, right? While some people already tried different approaches you usually still go with serialization as it was the most convenient way by now. However, generating JSON in your code leads to a couple of issues. It's in your codebase, it has to be compiled, etc. Changes require new releases and you often repeat yourself in various places or apps.

This is especially true when I hear people talk about Adaptive Cards and how they use them. Even some of the Microsoft Examples on how to use the BotFramework for MS Teams say you should do something like this:

// Create card
    var card = new AdaptiveCard(new AdaptiveSchemaVersion(1, 0))
    {
        // Use LINQ to turn the choices into submit actions
        Actions = choices.Select(choice => new AdaptiveSubmitAction
        {
            Title = choice,
            Data = choice,  // This will be a string
        }).ToList<AdaptiveAction>(),
    };

Now think about what happens when you want to change anything on your card, add something or even allow someone like your customer to edit this card? Literarily impossible.

With Adaptive Cards Templating data is completely separate from the card layout as such. This means your card template can be anywhere. In your code, in a database or even on a completely remote server fetched by URL.

To render the card you just bind your data onto your template using the template library.

This, for example, is one of the templates we use in our VS Code app: https://templates.adaptivecards.io/teamwork.com/projects/task.json

If you’ve seen code for Adaptive Cards before you should be familiar with it, however, there is no data in it just a lot of placeholders as described above. This template is loaded at runtime when people use our extension.

Adaptive Card rendered in VS Code ( JS / Typescript)

The extension is open-source and available on Github https://github.com/Teamwork/vscode-projects in case you want to have a look at how we did it.

This gives us quite a few interesting options. Let's admit we want to change something in the template, we do not have to do any new release, we don’t do any code changes. We update the template and its changed for all customers using the VSCode extension straight away.

An additional advantage is that you can re-use the same template in various places and can even share it with other people to allow them to use it if you want to. It is just a template, no private data in it.

It's not yet available but we also use the same template in our Visual Studio Pro extension, again the same template from that link above.

Adaptive Card in Visual Studio Pro ( WPF )

Template Repository and sharing templates

I mentioned templates fetched from a remote URL and also “sharing” of templates earlier. Yes, that's becoming a thing with templating.

As templates do not contain any data you can absolutely share the templates with other people. This is especially interesting when talking about common data such as Github issues or weather data, financial reports or data from Microsofts Graph API.
If a template works for one person it surely works for more, if one person invested time to build a template for let's say Github, there may be other people who would use the template for something they work on.

We are working on a Github Integration for one of our Products and we wrote an Adaptive Card template for it. https://templates.adaptivecards.io/github.com/issue_webhook.json

Adaptive Card showing Github Issue within Teamwork Projects ( Knockout / Javascript )

As you might have noticed earlier, the links are all based on https://templates.adaptivecards.io

The developers behind Adaptive Cards have created a proof of concept repository (similar to like npm or docker hub) where anyone can upload templates and make them available. They are working to create a lot of templates for commonly used data like all OData types for MS Graph but also things like flight reports. We added our own templates to that repository to allow anyone who wants to work with Teamwork tasks to use our template. We also shared our Github Template which might get some changes sooner or later.

If you have a template or suggested changes, you can go ahead and add a PR to the repository, it's open-source!

https://github.com/microsoft/adaptivecards-templates

Wrapping things up

In this post, you heard about Adaptive Cards as such, templating and even the template repository. There are a lot more things you can do with these tech pieces but I want to leave that to your imagination for now. I’ll try to cover more topics and examples in more posts later on.

In case you have any questions on all this feel free to reach out here in the comments or on twitter @TimCadenbach

AdaptiveCards just got a ton better

2021-01-05T00:00:00Z

With AdaptiveCards 1.3 (also 2.1.0 ) cards got a relatively simple but really powerfull change. All input fields now have a new property called “label”

Yea…a new field label but how does this make cards simpler?
Pretty simple. Take this card , made with AdaptiveCards 1.2:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.2",
    "body": [
        {
            "type": "TextBlock",
            "text": "Your Family Name"
        },
        {
            "type": "Input.Text",
            "placeholder": "Your family name...",
            "label": "Family Name",
            "isRequired": true,
            "errorMessage": "This field is required",
            "id": "familyname"
        },
        {
            "type": "TextBlock",
            "text": "Your Name"
        },
        {
            "type": "Input.Text",
            "placeholder": "Placeholder text",
            "label": "Your first name...",
            "id": "firstname"
        },
        {
            "type": "TextBlock",
            "text": "Date of Birth"
        },
        {
            "type": "Input.Date",
            "isRequired": true
        },
        {
            "type": "TextBlock",
            "text": "Email"
        },
        {
            "type": "Input.Text",
            "placeholder": "email@domain.com",
            "id": "email"
        },
        {
            "type": "TextBlock",
            "text": "Password"
        },
        {
            "type": "Input.Text",
            "placeholder": "Placeholder text",
            "id": "pwd"
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Sign Up"
        }
    ]
}

Notice how I said “simple” and you had to scroll all the way through the looong JSON Code? In fact, this card is pretty simple when we look at the rendered card:

Rendered Card

However, to build the card we had to do a lot of things, and for every input we needed 2 AdaptiveCard Controls. An Input.Text and a Textblock.

Now, lets compare things and have a look at the exact same card, made with Adaptive Cards 1.3:

Wow….thats a lot less JSON Code than what we had before isn’t it? In fact its half the amount of controls needed to get the exact same result as before.

With AdaptiveCards 1.3 every Input has a “Label” property, this property automatically renders the text label above the input and you no longer have to do that yourself. You still can, if you want to tho. But this effectively means that you in many many cases only need half the controls to get the same card result. Thats already great isn’t it?

But thats not all of the great news!!!

Client Side Input Validation!

Yes, thats right, you’ve read it right. With AdaptiveCards 1.3 there’s now input validation on all input fields. You can now do things like making sure people can only enter valid emails or specific range dates etc pretty much anything you can do with either min/max or regex can be done.

Using the input validation is pretty simple. Take a look at this part for example:

A simple “Input.Text” but its validated against regex making sure the password entered follows specific rules. In this case 1 lower char, 1 upper, 1 special and minimum 8 chars required.

AdaptiveCard showing validation errors

Additionally you can add a custom error message when validation fails. You can try the actual working card here: simple-signup-form-with-validation

So what exactly can I do with this?

Well, you can validate all inputs a user does on any given AdaptiveCard, some examples but not limited to are:

Validating text fields based on regex, anything you can do with regex, you can validate.
Validating Dates, ie requiring a min or max date value on fields
Numeric limitations, max number 1000? yea go for it.
Enforce specific formats. You want the user to input something in a spefic format like emails, zip codes or generally something like “no spaces”. You can do this now aswell.
and much more….

All validations happen on clientside before the actual card is submitted to the server.

That said have a look at www.madewithcards.io/cards we have some 1.3 and input validation samples there aswell.

You can get the new AdaptiveCards version from Nuget or NPM as usually but should consider installing 2.1.0 or 2.0.0 which is a new version fully backwards compatible and includes all the new features.

How to use the Teamwork Projects SDK

2020-02-12T00:00:00Z

Using the Teamwork Projects SDK

Recently, a new version of the Teamwork .Net SDK was released and I’d like to give you a few examples on how this can be used to make development for Teamwork Projects a lot easier when working with .Net.

To begin with, we need to add the library. As its currently still listed as pre-release in nuget we need to add the IncludePreRelease param:

install-package Teamwork -IncludePrerelease

As of writing this theres a .net core and .net 4.6+ version available.

Once we have the library loaded we need to get an authentication token to be used with the api and also the base url for the installation. This part can only be partly done with the SDK.

Getting an Access Token to be used with the client

You need to understand how Teamwork’s App Loginflow is working. Once you have that configured and and ready to receive the callback from the loginflow the SDK offers a handy function to make parsing the callback and fetching the actual access token a lot easier:

using Teamwork;
using Teamwork.Shared;
using Teamwork.Shared.Common;
private async Task<Teamwork.Client> HandleOauthAuthentication(string code, string state)
{
var response = await LoginFlow.TeamworkLoginFlow.GetLoginDataAsync(code);
// Use response to initialize a new instance of the Teamwork APi Client
return Client.GetTeamworkClient(
pDomain: response.AccountData.Account.URL,
pApiKey: response.TokenData.AccessToken,
pUseOauth: true);
}

Handling callback form AppLoginflow and getting a new client instance

The instance of the Teamwork API client is everything you need to start working with the API and actual data.

// Get all people in installation
var people = client.Projects.People.GetPeopleAsync();
// Get status updates by people in installation
var latestStatusMessages = client.Projects.People.GetPeopleStatusAsync();
// Find a person by email
var personByMail = client.Projects.People.GetPersonByMailAsync("max@teamwork.com");
// Get all active Projects
var projects = client.Projects.Projects.GetAllProjectsAsync(OnlyStarredProjects?)
// Get a specific project and its details by id
var project = client.Projects.Projects.GetProject(theID);
// You can chose to include tasks, milestones, people etc here
// Get all boards of a project
var boards = client.Projects.Boards.GetProjectBoardssAsync(theId);
// return time tracking totals for a given project and user
var totals = client.Projects.Time.GetTotals_Project(project,userid)
// Search for anything in Projects
// first param is the search term
// second is the type we are searching for
// available types are task, project, comment, message, notebook, person
var results = client.Projects.Projects.Search("Whatever we want to search for", "task")

Examples how to fetch data from Teamwork Projects usind the SDK

We can also add or modify all items in Teamwork Projects. This can be done in a similarly easy way to fetching data. Lets just have a look at how we would add a new task. To add a task we need to have a projectid and optionally a tasklist, both can be retreived from the example calls above.

// Create a new TodoItem instance
var newTask = new TodoItem() {
    Description = "This is a new task we want to add",
    Content = "The Title for my new task"
};
// And add it as task to a project
// tasklist id can be left blank, the task will be added to an "Inbox" tasklist
// also we can add it as a subtask and assign the parenttask
var result = await client.Projects.Projects.AddTodoItem(
pTodoItem: newTask,
pProjectId: TheProjectId,
pTaskListId: TheTaskListId
pIsSubTask: IsSubTask
pParentTask: ParentTask);
//if we want to we can complete our newly created task right away,
//the result will be the taskid of the newly created task
var ok = await client.Projects.Tasks.CompleteTask(result.Id);

Add a new task

These are pretty much the basics of what you can do with the SDK, however theres a lot more and its constantly updated so always worth to update when a new version comes out.

A few more examples:

// Lets just like a comment
var ok = await client.Projects.Reactions.LikeItem("comment", "commentId");
// we can even send messages on teamwork chat!
var ok = await client.Projects.Chat.SendMessage("the message i want to send", "the RoomId");
// Update your status
var ok = await client.Projects.Me.AddNewStatusMessage("Gone Fishin");
// Or a more complex example, create a company, add a person and
// finaly create a project for the new company
// first add the company
var company = new Company() {
Name = "MyNewCompany"
};
var companyId = await client.Projects.Companies.AddCompany(company);
// Now add a person and assign it to the newly created company
var newPerson = new Person() {
EmailAddress = "max@teamwork.com",
FirstName = "max",
LastName = "miller",
CompanyId = companyId
};
var ok = await client.Projects.People.AddPerson(newPerson);
// Finally add a project for the newly added company
var projectToCreate = new Project() {
Name = "My New project",
CompanyId = companyid
};
var ok = await client.Projects.Projects.AddProject(projectToCreate);

The SDK is available on Github: https://github.com/Teamwork/dotnet .
If you want to add something or request a change or even if you just have an issue, feel free to add things on Github. The developers always answer fast and love to help.