jcode/skills/write-my-paper/writing-guide.md

Writing guide: section by section

Read the section you are about to write, then write it into paper/sections/<name>.tex. Every section is plain LaTeX without \section preamble tricks; cite with \citep{key} / \citet{key} (natbib), reference with \cref{fig:x} / \cref{tab:x} / \cref{sec:x}.

General style

• One claim per sentence; every claim is backed by (a) a table/figure of this paper, (b) a citation, or (c) a derivation. If none exists, delete the claim.
• Use the method name macro \ours{} consistently. Define every symbol once, at first use.
• Present tense for what the paper does ("we propose", "Table 2 shows"), past tense for what was run ("we trained for 100 epochs").
• No hype words: novel, groundbreaking, remarkable, significantly (unless a test was run), state-of-the-art (unless compared against the current best published number on the same benchmark with the same protocol, cited).
• Numbers: same number of decimals as the table; units; "x pp" for percentage-point differences. Quote only values from paper/data/summary.csv, the generated tables, or a cited paper (then cite it in the same sentence).
• Paragraphs open with a topic sentence; a reader who reads only first sentences gets the story.

abstract.tex (150-250 words, no citations, no math)

1. Context + problem (1-2 sentences). 2. Gap: why existing methods fall short (1).
2. What we do: method in one sentence, the key idea (1-2). 4. Evidence: datasets and the headline result with a number (1-2). 5. Implication / what is released (1).

introduction.tex (~1 page) - \section{Introduction}\label{sec:intro}

• P1 Motivation: the task and why it matters, with 2-4 citations.
• P2 The gap: what current approaches do and the specific limitation, cited.
• P3 Our idea: the insight in plain words; optionally point to the teaser figure.
• P4 Evidence: what was evaluated and the headline numbers.
• Contributions as an itemize of 3-4 bullets, each concrete and checkable ("We show on X and Y that ... improves Z by N pp over B", not "extensive experiments").
• Optional last line: paper outline (skip if tight on space).

related_work.tex (0.5-1 page) - \section{Related Work}\label{sec:related}

• 2-4 \paragraph{Theme.} blocks, grouped by idea, not a list of papers.
• Each paragraph: what the line of work does (cite 3-8 papers), then how this paper differs in one sentence. Never misrepresent a paper: describe only what its abstract/text (as summarised in research.md) says.
• Cite the original paper of every baseline, dataset, model and major library used.

method.tex (1.5-2.5 pages) - \section{Method}\label{sec:method}

• Problem setting / notation first (\subsection{Problem Setting}): inputs, outputs, objective, as equations.
• Then the method, in the order the code executes it. Every equation must match the code (loss terms, normalisations, hyperparameters as symbols). Read the code again while writing this; if the code differs from the "intended" method, describe the code.
• An algorithm box (algorithm + algorithmic) if there is a training/inference loop.
• Complexity / cost if relevant (params, FLOPs, wall-clock - only if measured).
• Design choices: say why, ideally pointing to an ablation.

experimental_setup.tex (~0.75 page) - \section{Experimental Setup}\label{sec:setup}

Reproducibility details taken from the code/configs, not invented:

• Datasets (cite each): size, splits, preprocessing, augmentation.
• Baselines (cite each) and how they were tuned (same budget?).
• Architecture, optimizer, learning rate + schedule, batch size, epochs/steps, weight decay, early stopping, seeds (number of runs), hardware and run time if logged.
• Metrics, with direction (higher/lower is better) and how they are aggregated (mean +- std over N seeds; test-set at last epoch or at best validation epoch).
• Put long hyperparameter tables in the appendix and reference them.

results.tex (1.5-2.5 pages) - \section{Results}\label{sec:results}

• \subsection{Main Results}: \input{tables/main} + 1 paragraph per finding. Each paragraph: observation -> numbers -> interpretation. Mention where the method does NOT win.
• \subsection{Ablations} (if variant/ablation runs exist): what each component contributes, \input{tables/ablation} or a bar figure.
• \subsection{Analysis}: learning curves, sensitivity to a hyperparameter, efficiency trade-off, qualitative examples - whatever the data supports.
• Figures: \begin{figure}[t]\centering\includegraphics[width=\linewidth]{figures/x.pdf} \caption{What is shown. What to notice. Shaded: +-1 std over N seeds.}\label{fig:x}\end{figure}. Captions are self-contained; every figure/table is referenced in the text before it appears.
• Significance: only call a difference significant if a test was run (the dagger marks in results.py tables); otherwise say "higher on average" and give std.

discussion.tex (~0.5 page) - \section{Discussion and Limitations}\label{sec:discussion}

• What the results mean, when to use the method, when not.
• Limitations honestly and specifically: few seeds, small datasets, single domain, no hyperparameter search for baselines, compute limits, missing comparisons. Reviewers trust a paper more when it names its weaknesses.

conclusion.tex (1 paragraph) - \section{Conclusion}\label{sec:conclusion}

Restate the problem, the idea, the evidence; one sentence of future work. No new claims.

statements.tex

\section*{Reproducibility Statement}: where code/configs/seeds are, which sections/appendix give the details. \section*{Broader Impact} (or Ethics Statement): 3-6 honest sentences; dataset licences if relevant. Keep what the target venue requires, drop the rest.

appendix.tex

\section{Additional Experimental Details}\label{app:details} (full hyperparameter table, compute), \section{Additional Results} (per-dataset tables, more curves). Every appendix section is referenced from the main text.

Title

Specific and searchable: ": for " or a finding-style title (" improves under "). No question titles, no puns unless the user wants them.

Self-review checklist (do it as a reviewer, write findings to paper/review.md)

• Is the contribution clear after page 1? Are claims in abstract/intro all supported by results?
• Are baselines fair (same data, budget, tuning)? Are the strongest relevant baselines there?
• Seeds/variance reported? Test set used only for final numbers?
• Are related works that do nearly the same thing cited and differentiated?
• Do equations match the code? Notation consistent? All symbols defined?
• Every figure readable in grayscale print, axes labelled with units, fonts >= 7pt?
• Limitations stated? Anything over-claimed ("significantly", "state of the art")?