Collaborative comments · a minimal design review

A minimal design for this project

Keep the contextual sidebar; make the laptop’s review directory the place where feedback becomes edits.

Scope: a small group reviewing mathematical HTML pages, with private comments and one maintainer. This is a focused review of primary research, a web standard and official product documentation; it is not a systematic review or a claim that one layout is universally best.

Reviewed 19 October 2026. Source findings and our design judgments are distinguished below.

Implementation update · 19 October 2026. The Iwahori workspace now supports whole-page and passage selection comments. An hourly Mac job downloads feedback to ~/collaborative-generation/local/comments/ and builds an offline HTML report, with Claude summaries when account capacity is available. Setup and directory guide. Persistent owner decision notes remain a proposed next step.

Later the same day. Comments became public at the owner’s request: readers highlight a passage to comment, every reader sees the highlights, and comment cards open in a side column beside the text (a bottom sheet on phones) with LaTeX rendered. The “private comments” scope above describes the design as reviewed.

What the evidence supports

Table 1. · Evidence relevant to commenting and local review.
source and evidence type	finding or established practice	design judgment for this project
NB · CHI 2012 classroom field study	In-place discussion supported questions about specific passages; the detailed analysis selected a particularly successful class where the instructor used feedback to change teaching.	Keep the proof visible while writing. Review comments regularly and publish an answer or an edit where useful. Classroom participation results do not establish effectiveness for a small research group.
Brush et al. · 2000; W3C · 2017 user studies + data standard	Document edits can detach annotations. W3C specifies exact quotation, surrounding text and source-state information.	Retain a stable block ID, selected passage and page revision. When a passage changes, show the saved context and flag it for checking; avoid guessing a new location.
Hypothesis export official product practice	Offers JSON, text, CSV and HTML exports. Its documented import does not restore replies and reattributes imported annotations to the importer.	Provide HTML for reading and JSON for the full record. If replies are added later, preserve parent IDs and original authors explicitly; test that exports retain them.
Zotero 6 official research-tool workflow	Annotations added to notes retain source information and links back to the original passage; notes can be exported to Markdown.	Every local feedback item should show the quotation separately from the comment and include “Open source”. Keep an editable plain-text format alongside the HTML.
Figma comments official product practice	Comments can be searched and filtered; resolved threads can be shown again and reopened.	Use Open / Resolved and one short decision note. Resolution should hide an item from the working list while retaining its history.
Local-first · Onward! 2019 systems research and design principles	Prioritizes ownership, offline use and long-term access to data held on the user’s devices.	Keep complete files that remain readable without the service. Our present architecture is cloud collection with local exports; a browser cache alone does not provide these ownership properties.

The exact controls, statuses and directory layout below are our synthesis. Product documentation demonstrates available patterns; it does not prove that copying a product’s full interface improves collaboration.

Two small interfaces

On the proof page

Name → passage → comment → Submit. Keep the quoted passage above the box, save the draft, and show a clear saved receipt. Put storage explanations and history under disclosures.

Keep names as explicitly unverified display labels. The current service collects private feedback; collaborative discussion would additionally require participant-visible threads and replies, with an explicit visibility policy.

On the laptop

One column of comments, one search field, Open / All. Each item shows name and time, source link, quotation, comment, Open / Resolved, and an optional decision note. Use readable text and horizontal separators.

Name · date and time                       Open
Proposition P1 · Open source ↗

Quoted passage
“Every primitive vector extends to a basis.”

Comment
Could you show the matrix when n = 2?

Decision / edit
Added the two explicit matrices.

[ Mark resolved ]

Illustrative content only. This is the recommended layout, not a deployed review application.

A directory that survives the next export

~/Documents/Trees-comments/
  index.html                 readable local review list
  comments.json              latest complete imported feedback
  review.json                your status and decision notes, keyed by comment ID
  archive/
    <UTC timestamp>.json     preserved export snapshots

Download → merge by comment ID → keep review decisions → regenerate HTML. Downloading feedback must never replace review.json; repeated downloads should not create duplicate review items.

Keep the received comment and timestamp unchanged. Record your response, resolution time and optional edit/commit reference separately. New comments enter Open; previously resolved comments remain resolved.

The local HTML should display imported visitor text as text, work offline and preserve source links. A status changed only in browser storage is a convenience copy; lasting decisions belong in the directory. If editing directly in HTML is implemented, it needs an explicit file-save mechanism or a small local helper.

This layout is proposed. The current exporter creates dated folders containing comments.json, comments.csv and review.md; those files already work offline, but review decisions are not merged into later exports.

What to keep, what to improve next

Keep: passage-specific comments, shared display names, durable private storage, UTC timestamps, stable submission IDs, browser drafts and owner-only exports.
First improvement: an offline HTML view over the exported records, with persistent review decisions stored separately from downloaded comments.
Second improvement: capture the page revision and quotation context so old comments remain interpretable after edits.
Close the loop: publish a concise approved response or update note after review. A private local resolution does not itself tell the collaborator what happened.

How to download the current archive · Current comment interface.

A small usability check should test three tasks: leave a comment on a proposition, find it after export, and resolve it without losing the decision on the next download. These are proposed acceptance checks, not measured results.

Sources for this review

Zyto, Karger, Ackerman & Mahajan. Successful Classroom Deployment of a Social Document Annotation System. CHI 2012, especially system description and instructor perspective.Field evidence from education; participation was required in the detailed case study.
Brush, Bargeron, Gupta & Cadiz. Robust Annotation Positioning in Digital Documents. MSR-TR-2000-95, 2000, especially §§3–6.Two studies of annotation positioning in revised documents.
W3C. Web Annotation Data Model §4.2.4 and §4.3. Recommendation, 2017.Interoperability standard; no claim of comparative UI effectiveness.
Hypothesis. Exporting and Importing Annotations.Current export formats and documented import limitations; accessed 19 October 2026.
Zotero. Zotero 6: Your research workflow, transformed. 2022, annotation notes and Markdown export.
Figma. View and manage comments.Search, filters, resolution and reopening; accessed 19 October 2026.
Kleppmann, Wiggins, van Hardenberg & McGranaghan. Local-first software: You own your data, in spite of the cloud. Onward! 2019.Ownership and offline access motivate the local archive; full real-time synchronization is beyond this minimal design.

Earlier review · teaching, coordination and the original prototype

Retained as design history. The focused review above describes the current task; interface descriptions below have been updated where superseded.

1 · Findings by component

Table 2. · Earlier evidence and design choices.
component	what prior practice shows	sources	for us
Comments in the margin	The most successful classroom deployment of the NB annotation tool was the one where the instructor changed his teaching in response to the comments. evidence thin per the 2012 review.	[1] [2] [3]	The value comes from the maintainer responding to comments, not from the tool's features.
Stable anchors	The Stacks project and Kerodon attach comments to permanent tags: no reader profiles, one comment form, and the human check is typing the tag's name. Stacks has more than 10,000 comments.	[4] [5]	Our block ids play the role of tags. Stable block ids locate the discussion; the current design also saves the quotation and source URL.
Measuring friction	Muddiest point: ask readers one question, “what was least clear?” Just-in-Time Teaching: read the answers, then revise before the next session. long classroom record	[6] [7] [8]	Read comments one by one; do not compute a rate (Friction).
Modelling the reader	Knowledge tracing needs many graded attempts per skill. People who know a topic least also judge their own knowledge least accurately. Open learner models: if a model is kept, show it to the learner.	[9] [10] [11]	No levels, inferred or self-reported. Keep a short summary of each reader and show it to them.
LLM memory	Generative agents keep a stream of raw observations and periodically write higher-level “reflections” from it; removing reflection made their behaviour less coherent.	[23]	Threads are the raw record; `readers/<login>.md` is the reflection, rebuilt from them.
Coordination	Polymath ran on open threads plus regular summaries by the project leads. Lean blueprints coordinate a proof through a dependency graph that shows the status of each node.	[12] [13] [14]	The concept graph is already the coordinating object. Comment badges belong on its nodes.
Off-the-shelf annotation	Hypothesis supports private groups, LaTeX in annotations, an embeddable client, and export of a group's annotations through its API. It anchors annotations to text with the W3C Web Annotation model.	[15] [16] [17] [24]	Considered first. Its API has no webhook, only a WebSocket feed or polling; since our laptop polls anyway, that no longer rules it out. The new affine-page composer takes the sidebar and selected-passage pattern, while a Cloudflare Worker creates a private GitHub issue for the visitor; no visitor GitHub account is needed.
AI tutors	In a field experiment, unrestricted GPT‑4 access lowered later exam scores by 17%; a tutor-prompted version showed no loss. A tutor designed around the course's own material outperformed active learning. Models fail on graduate-level mathematics.	[18] [19] [20]	Ground replies in the page and glossary, label them unverified, and never let the bot change the mathematics.
Privacy	A release is k‑anonymous only if each record matches at least k−1 others. With small k, breaking counts down by level identifies people.	[21]	Public pages show approved notes only, no counts.
Build order	“A complex system that works is invariably found to have evolved from a simple system that worked.”	[22]	Start with the smallest loop that works.

2 · NB, read again with LLMs

NB [1] put threaded discussion in the margins of lecture notes; its best class (91 students, one semester) wrote 14,258 annotations.

Table 3. · Questions raised by the NB deployment.
NB found	question for us
In a coded sample, 85% of replies were students answering students; the instructor took part in 10.4% of discussions. Students called replies timely because of peer answers and email notifications.	Q1. With a handful of collaborators, peers will not answer within minutes, and an AI will. Should it reply at once, after a delay, or only when no person has answered, so that it does not take over the peer teaching that made NB work?
The instructor read the comments from 11 pm and changed the next morning's lecture. 13 sampled discussions were answered on a nearby thread, and the authors asked for one reply to several co-located threads.	Q2. An LLM can read every thread on a block and write one synthesis. Should the bot's main job be answering single comments or summarising a block's threads for the author, and does the author still need to read the raw comments, where NB's value came from?
Annotations were required (“decent effort” earned full credit), and instructors discarded each term's annotations: the act of annotating was the point.	Q3. If an LLM turns resolved threads into permanent notes, later readers get a page that is already annotated. Does that help them or remove the questions they would have asked, and what makes collaborators comment when nothing requires it?

3 · A small interface beside the proof

These are interface choices drawn from prior systems, not a claim that the new composer has been evaluated.

Table 4. · Three patterns used by the affine-page comment sidebar.
pattern	source	implementation
Keep the passage beside the composer	Hypothesis annotation sidebar [15]	A persistent right-hand panel, with the block heading and selected text above one comment box.
Attach discussion to a stable mathematical object	Stacks tag comments [4]	Definition, proposition, proof-step and figure ids accompany the comment in the GitHub issue.
Store the quotation with its source	W3C Text Quote Selector [17]	A selected passage is retained alongside the page URL and anchor; full automatic re-anchoring is not implemented.

The current composer keeps drafts and submission history in browser localStorage. It archives verified comments in D1 before attempting GitHub delivery, and distinguishes an archive receipt from confirmation of the GitHub copy.

Try the affine page · Deployment and delivery contract.

References

S. Zyto, D. Karger, M. Ackerman, S. Mahajan. Successful classroom deployment of a social document annotation system. CHI 2012.
K. Miller, B. Lukoff, G. King, E. Mazur. Use of a social annotation platform for pre-class reading assignments in a flipped introductory physics class. Frontiers in Education 3 (2018).
E. Novak, R. Razzouk, T. Johnson. The educational use of social annotation tools in higher education: a literature review. Internet and Higher Education 15(1) (2012) 39–49. doi:10.1016/j.iheduc.2011.09.002
The Stacks project: stacks.math.columbia.edu (comments per tag; statistics).
Kerodon: kerodon.net, built on P. Belmans' Gerby (announcement).
F. Mosteller. The “muddiest point in the lecture” as a feedback device. On Teaching and Learning (Harvard–Danforth Center) 3 (1989) 10–21.
G. Novak, E. Patterson, A. Gavrin, W. Christian. Just-in-Time Teaching: Blending Active Learning with Web Technology. Prentice Hall, 1999.
T. Angelo, K. P. Cross. Classroom Assessment Techniques: A Handbook for College Teachers. 2nd ed., Jossey-Bass, 1993.
A. Corbett, J. Anderson. Knowledge tracing: modeling the acquisition of procedural knowledge. User Modeling and User-Adapted Interaction 4(4) (1994) 253–278.
J. Kruger, D. Dunning. Unskilled and unaware of it. J. Personality and Social Psychology 77(6) (1999) 1121–1134. doi:10.1037/0022-3514.77.6.1121The size of the effect is disputed (Krajc & Ortmann 2008). The point used here is weaker: self-reported level is noisy.
S. Bull, J. Kay. Student models that invite the learner in: the SMILI open learner modelling framework. IJAIED 17(2) (2007) 89–120; and SMILI☺, IJAIED 26 (2016).
T. Gowers, M. Nielsen. Massively collaborative mathematics. Nature 461 (2009) 879–881.
J. Cranshaw, A. Kittur. The Polymath project: lessons from a successful online collaboration in mathematics. CHI 2011, 1865–1874.
P. Massot. leanblueprint, used for e.g. the Polynomial Freiman–Ruzsa formalization.
Hypothesis: annotation basics (private groups, LaTeX in annotations).
Exporting a group's annotations through the Hypothesis API (script by a Hypothesis developer).
W3C. Web Annotation Data Model. Recommendation, 23 Feb 2017.
H. Bastani et al. Generative AI without guardrails can harm learning: evidence from high school mathematics. PNAS 122(26) (2025). doi:10.1073/pnas.2422633122
G. Kestin, K. Miller, A. Klales, T. Milbourne, G. Ponti. AI tutoring outperforms in-class active learning. Scientific Reports 15 (2025) 17458.Two-week intervention; long-term retention not measured.
S. Frieder et al. Mathematical capabilities of ChatGPT. NeurIPS 2023 Datasets & Benchmarks.Tests 2023 models. Newer models are stronger, but answers still need checking.
L. Sweeney. k-anonymity: a model for protecting privacy. Int. J. Uncertainty, Fuzziness and Knowledge-Based Systems 10(5) (2002) 557–570.
J. Gall. Systemantics: How Systems Work and Especially How They Fail. 1977 (first ed. 1975 as General Systemantics).
J. S. Park, J. O'Brien, C. Cai, M. R. Morris, P. Liang, M. Bernstein. Generative agents: interactive simulacra of human behavior. UIST 2023.
Hypothesis. Real Time API (WebSocket notifications; documented as early-stage).