Honest Engineering:
Why Static Docs are Dead.

Most project management tools suffer from a "context gap." You have your tasks in Jira/Linear, your architecture docs in Confluence/Notion, and your actual diagrams in Lucid/Excalidraw.

By the time a developer opens a ticket, the diagram they need is three weeks out of date, and the "technical spec" is a wall of text that nobody has read since the kickoff meeting.

The "Wiki-First" Philosophy

When we started building Klority, we decided that the Wiki shouldn't be a secondary tab. It should be the source of truth that powers the tasks. We wanted to answer the question: *How do we make documentation as low-friction as writing code?*

Technical Challenge: The Live Diagram Problem

Embedding diagrams usually means taking a screenshot or using a heavy iframe. Neither is ideal. Screenshots rot; iframes are slow and often break searchability.

Our solution was to treat diagrams as code. Using **Mermaid.js**, we can store diagrams as simple text strings within the Tiptap JSON document structure.

graph TD
  A[Client] -->|HTTP| B(API)
  B --> C{Auth}
  C -->|Success| D[Database]

Implementing the Mermaid Extension

We built a custom Tiptap extension that intercepts the slash command (`/mermaid`) and renders a live, editable node. The node-view handles the local state for the Mermaid syntax and uses a debounced renderer to show the SVG in real-time.

This is "Honest Engineering"—giving you the tools to document perfectly what you are building *as* you build it.

Why it Matters

When your Mermaid diagrams live inside your sprint context:

• PR Reviews are faster: Reference a live sequence diagram in the ticket description.
• Onboarding is automatic: New hires find the architecture right next to the issues they are assigned.
• Predictability increases: Complex system changes are easier to visualize during grooming.

Conclusion

Klority isn't just about moving cards across a board. It's about building a collective brain for your engineering team. By integrating live diagrams and wiki-first patterns, we're closing the gap between "what we planned" and "what we built."

Curious about the implementation? Check out our Security Docs (rendered with this same tech) or sign up now.