Why I Built DocShare: Reviewing HTML Docs With My Team and AI

Most of my week as a tech lead isn't code — it's documents. Specs and requirements with the BA team, architecture write-ups, sequence and flow diagrams, incident reports, design proposals. And over the last year almost all of them have ended up as one format: HTML. This is the story of why, and the small tool I built to make reviewing them bearable: DocShare.

Why I draft documents in HTML

I lean on AI heavily for first drafts — turning a messy call with the BA team into a structured spec, or sketching a diagram from a few bullet points. Once you do that often, the format you choose stops being cosmetic and starts costing you real time and tokens. HTML won for a few concrete reasons:

• AI handles it better. Models read and edit HTML cleanly — headings, tables, lists, and even inline SVG diagrams are plain text the model already understands. Ask for a change and you get back valid markup, not a mangled binary.
• It's cheaper in tokens. A .docx or PDF is a zipped bundle of XML and styling noise; pasting its guts at an AI burns tokens on markup that has nothing to do with the content. HTML is close to the signal, so more of the context window goes to the actual document.
• Diagrams live inline. Flowcharts and sequence diagrams can be SVG or simple markup right inside the doc — versioned with the text, editable by AI, no screenshot round-trips.
• It renders anywhere and diffs cleanly. A browser opens it, and being text means I can actually see what changed between versions instead of guessing.

The part that was painful

Producing HTML was the easy half. The hard half was reviewing it with people who don't live in a code editor. My BA teammates and stakeholders aren't going to open a pull request to leave a comment on paragraph three. So feedback came back as Slack messages, screenshots with arrows, or "see my notes in the attached Word copy" — and then I'd spend an hour reconciling all of it back into the HTML by hand before I could even ask AI for the next revision.

What I wanted was dead simple: host the rendered HTML, let people comment directly on the parts they mean, and hand the whole conversation to AI in one move. Nothing did exactly that, so I built it.

What DocShare does

DocShare is a collaborative HTML review app. There's no setup — you paste HTML or upload an .html file and it's live. From there:

• Comment on each part. Click any heading, paragraph, list item, or table cell to start a thread. Comments stay anchored to that block, so feedback never drifts away from what it's about.
• Versions and rendered diffs. Every version is kept. Compare any two as a rendered redline and step through the changes — the same "what actually changed" view I wanted from plain HTML, without the manual squinting.
• Share by email. Invite collaborators by email; they get a link, sign in, and comment, with updates appearing live for everyone.
• Export feedback as an AI prompt. This is the piece I cared about most — collect every comment and export it as a single prompt to fix the doc with AI.

How it fits my actual workflow

The point of all of this is a tight loop between AI and the humans who need to sign off:

1. Draft the spec, report, or diagram as HTML — usually with AI doing the first pass.
2. Paste it into DocShare and share the link with the BA team.
3. They comment on the exact sections they mean, anchored in place.
4. Export all of that feedback as one prompt, hand it to AI, and get a revised version.
5. Compare the new version against the old as a rendered diff, then send it round again until everyone's happy.

What used to be a scattered mess of screenshots and re-typed notes is now a single thread that AI can act on directly.

Try it

It's built for design reviews, reports, and AI-generated pages that need a human pass — and it's free. If you work with documents and AI the way I do, give it a spin: docshare.gatetroy.com. I'd genuinely like to hear what breaks or what's missing.