Scientific Writing
Conventions for structuring research papers and for the drafting workflow.
This skill owns the paper's structure and process; it delegates:
- citation finding/verification and the search-protocol appendix to
backing-claims,
- LaTeX mechanics (semantic environments, restatable theorems, dual
article/slides builds, noweb appendices) to latex-writing,
- reading and uploading annotated drafts to remarkable.
Questions, hypotheses, contributions: full traceability
The skeleton of the paper is the mapping between contributions, research
questions and hypotheses. Enforce all of these:
- Two kinds of research questions, separately numbered.
Substantive questions ask about the world; methodological questions
ask whether the study's own instruments work (do independent
classifications agree? does coding from logs match coding from
think-aloud?). Methodological questions get their own environment and
counter, so they never renumber the substantive ones. See
references/question-structure.md for the LaTeX pattern.
- Every contribution is held to account by a research question.
The introduction has a Contributions subsection; each listed
contribution names the question that tests it. A methodological
contribution (an instrument, a coding scheme, a triangulation) gets a
methodological question. If a contribution has no question, either add
the question or drop the claim.
- Hypotheses are predicted answers. Each hypothesis answers exactly
one question; descriptive/exploratory questions have no hypothesis and
say so. If an overarching claim is not directly falsified but supported
by inference to the best explanation, state that explicitly in the
method overview.
- State once, restate twice. Each question and hypothesis is stated
once (introduction/theory) in a restatable environment, restated in
the method overview together with how it will be answered, and
restated in the conclusions together with its answer so far. Reference
by
\cref, never literal "RQ1"/"H2".
Method section
- Overview before details: open by restating every question and
hypothesis with its mode of answer (which data, which test, which
section), then give the details in subsections.
- Data collection in chronological order of the study, and motivate
each instrument at the point in time it is used: if an instrument is
administered at start and end, the start section motivates only the
start administration and a separate end-of-course section motivates the
re-administration.
- Do not duplicate a companion study's instrument. When a companion
paper collects data in the same setting (same course, same cohort),
use its measurements instead of writing a parallel instrument, and
let this study's own instruments test only what the companion's do
not cover. State the division of labour in the method (which scores
come from where), keep the instruments' platform titles
distinguishable for participants and analysis alike, and discuss
alternatives (e.g. established inventories) against the combined
design.
- Validated instruments stay verbatim. Do not reword items of a
validated questionnaire, even where wording fits the setting poorly;
note the tension in prose instead. Search for and cite published
criticisms of the instrument, and derive robustness checks from them
(e.g. scoring a subscale separately).
- Guard against circularity: a classification must never be derived
from the same data it is later correlated with; say explicitly which
sources each classification uses.
Literate-program appendices
Every questionnaire/quiz/survey the study administers, and every
quantitative analysis it runs, is a literate program in the paper's
appendix: one noweb source that weaves into the appendix chapter and
tangles into the runnable artifacts (e.g. the platform's quiz JSON, the
analysis script).
- The prose documents the data-file schemas; this doubles as the study's
code book.
- Instrument definitions and their analysis share constants (e.g. item
titles as result-file column keys) so they cannot drift apart —
ideally in the same source file, side by side.
- Uniform instruments are generated, not hand-written. When the
items share one form (a validated questionnaire: twenty items, the
same five responses), do not tangle the platform's JSON directly:
state the instrument once — titles, items, response anchors,
instructions — in a constants chunk, tangle a small generator that
unfolds it into the platform files, and have the analysis program
include the same constants chunk (titles find the reports, anchor
texts map answers back to scores). Reference: vt-debug's
rspq.nw
(make_rspq.py + analyze_rspq.py).
- Cross-reference both ways: the method section points to the appendix
program, the appendix points back to the sections that motivate each
piece.
- End-to-end automation, both directions. The programs reach into
the platform themselves: they create the instruments (e.g.
canvaslms quizzes create) and they fetch the results back (e.g.
the student-analysis report via the platform CLI's own importable
machinery) — course names and instrument titles are known constants,
so nothing is clicked or downloaded by hand. Where a fetch cannot be
automated yet, mark it XXX with a tracking issue rather than settling
for a manual step silently.
- LLM-assisted coding, human-verified. For open-text answers that
need qualitative coding, the analysis program pre-codes them with an
LLM (the
llm package; prompt states the coding scheme, answers in
JSON) and writes the suggestions into columns separate from the
human coder's verified codes — the sheet always shows which is which,
and the human's codes are the data.
- Build mechanics (article-only noweb.sty, Makefile rules, tangle
recipes, the syntax-highlighted weave): latex-writing's
references/dual-beamer-article.md section "Literate-program
appendices", and the literate-programming skill for the standard
tominted recipe.
- Validate tangled artifacts in the round that creates them (JSON parses,
Python compiles, quiz validators pass) — and test instrument creation
end to end against a sandbox course before the real one.
Review rounds
A draft iterates in review rounds; each round is one atomic unit and lives
on its own branch with its own PR. Name both after the draft version
the round produces — branch review-round-vN, PR to the default branch
titled "Review round: draft vN (YYYY-MM-DD)" — so branch, PR, commit
message and reMarkable name all carry one identifier (the round that
processes v48's comments and uploads v49 is review-round-v49; round
counts and draft versions diverge, so never number by round):
- Open the round: branch
review-round-vN off the default branch. The
round's work happens here; the PR opens when the round's draft is
uploaded.
- Read all annotated pages of the previous draft (remarkable skill:
content_type=annotations to list the pages, render_merged images to
read the handwriting).
- Interpret every comment; apply all edits of the round.
- New literature needs discovered in a round go through backing-claims
(find, verify, provenance block) and into the search-protocol appendix
in the same commit.
- Rebuild all outputs; verify: zero errors, no unresolved references,
restatement counts unchanged where expected.
- One commit per round, without asking; the commit message lists the
round's changes and names the draft version it produces (
"This commit is the version uploaded to reMarkable as draft YYYY-MM-DD, vN"), so
every uploaded draft maps to exactly one commit. Commit at upload
time — never upload a draft whose source is uncommitted. Push after
committing — the paper repo and, when skills changed, the skills repo
(mind that the first push of a fresh repo needs git push -u origin <branch>; a GitHub repo that only ever received issues counts as
fresh).
- Upload the new draft as
"<Title> (draft YYYY-MM-DD, vN)" with N
incremented.
- Open the PR (
gh pr create), listing the round's changes; use
closes #N for issues the round resolved, so merging closes them.
Merging the PR ends the round; the next round starts at step 0 with a
new branch and PR.
Cite the principle wherever the argument is made
When a passage argues from a theoretical principle the paper rests on — the
design rationale of an instrument item ("a test of discernment must not
point out the aspect"), the wording of a stem, a coding or analysis choice —
cite the principle's source in that passage (e.g. \autocite[p.~91]{NCOL}),
not only where the principle was first introduced. The citation is the
support for the argument: a reader of an appendix paragraph does not carry
the introduction's citation with them, and a reviewer sees an unsupported
claim. This holds for every instance — each item rationale that invokes the
principle, each stem redesign in a review round. "Already cited earlier in
the paper" is not a reason to omit it; repeating the same key and page is
correct, not redundant. (Verification per backing-claims happens at the
first use; later uses of the same verified claim reuse the key and page.)
Open questions and pending decisions
- Mark open decisions with
% XXX and deferred work with % TODO in the
source, stating the alternatives and what resolves them; resolve or
carry them forward consciously each round — never silently drop one.
- Mirror them as GitHub issues whenever the paper repository has a
GitHub remote (
git remote -v). This is standing authorisation: create
the issues with gh issue create without asking. Conventions:
- One issue per XXX/TODO item; the title states the decision or task,
the body gives the file and section, the context, the alternatives,
and what resolves it.
- Annotate the source comment with the issue number —
% TODO(#12): ...
— so source and tracker stay linked.
- Per round: new XXX/TODO items get new issues; items resolved in the
round get their issues closed (
gh issue close N --comment ...) in
the same round, referencing the commit.
- An item tracked elsewhere too (e.g. a
nytid todo for work the
author must do personally) still gets the issue; note the cross-link
in both.
- Anonymise course/institution details before submission (keep a
% TODO
at the top of the method section until done).
Checklist (per round)
1---2name: scientific-writing3description: Structure and workflow conventions for research papers. Use proactively when (1) writing or revising a paper draft, its introduction, method, results or conclusions, (2) adding research questions, hypotheses, contributions, questionnaires or analyses to a paper, (3) processing a review round on a draft, or (4) starting a new paper repository. Covers question-hypothesis-contribution traceability, substantive vs methodological research questions, literate-program appendices for instruments and analyses, method-section chronology, and the review-round loop.4metadata:5 source: https://skillmd.com/skills/dbosk/scientific-writing6---78# Scientific Writing910Conventions for structuring research papers and for the drafting workflow.11This skill owns the paper's *structure and process*; it delegates:1213- citation finding/verification and the search-protocol appendix to14 **backing-claims**,15- LaTeX mechanics (semantic environments, restatable theorems, dual16 article/slides builds, noweb appendices) to **latex-writing**,17- reading and uploading annotated drafts to **remarkable**.1819## Questions, hypotheses, contributions: full traceability2021The skeleton of the paper is the mapping between contributions, research22questions and hypotheses. Enforce all of these:23241. **Two kinds of research questions, separately numbered.**25 *Substantive* questions ask about the world; *methodological* questions26 ask whether the study's own instruments work (do independent27 classifications agree? does coding from logs match coding from28 think-aloud?). Methodological questions get their own environment and29 counter, so they never renumber the substantive ones. See30 `references/question-structure.md` for the LaTeX pattern.312. **Every contribution is held to account by a research question.**32 The introduction has a Contributions subsection; each listed33 contribution names the question that tests it. A methodological34 contribution (an instrument, a coding scheme, a triangulation) gets a35 methodological question. If a contribution has no question, either add36 the question or drop the claim.373. **Hypotheses are predicted answers.** Each hypothesis answers exactly38 one question; descriptive/exploratory questions have no hypothesis and39 say so. If an overarching claim is not directly falsified but supported40 by inference to the best explanation, state that explicitly in the41 method overview.424. **State once, restate twice.** Each question and hypothesis is stated43 once (introduction/theory) in a restatable environment, restated in44 the method overview together with *how* it will be answered, and45 restated in the conclusions together with its answer so far. Reference46 by `\cref`, never literal "RQ1"/"H2".4748## Method section4950- **Overview before details**: open by restating every question and51 hypothesis with its mode of answer (which data, which test, which52 section), then give the details in subsections.53- **Data collection in chronological order** of the study, and motivate54 each instrument *at the point in time it is used*: if an instrument is55 administered at start and end, the start section motivates only the56 start administration and a separate end-of-course section motivates the57 re-administration.58- **Do not duplicate a companion study's instrument.** When a companion59 paper collects data in the same setting (same course, same cohort),60 use its measurements instead of writing a parallel instrument, and61 let this study's own instruments test only what the companion's do62 not cover. State the division of labour in the method (which scores63 come from where), keep the instruments' platform titles64 distinguishable for participants and analysis alike, and discuss65 alternatives (e.g. established inventories) against the *combined*66 design.67- **Validated instruments stay verbatim.** Do not reword items of a68 validated questionnaire, even where wording fits the setting poorly;69 note the tension in prose instead. Search for and cite published70 criticisms of the instrument, and derive robustness checks from them71 (e.g. scoring a subscale separately).72- **Guard against circularity**: a classification must never be derived73 from the same data it is later correlated with; say explicitly which74 sources each classification uses.7576## Literate-program appendices7778Every questionnaire/quiz/survey the study administers, and every79quantitative analysis it runs, is a **literate program in the paper's80appendix**: one noweb source that weaves into the appendix chapter and81tangles into the runnable artifacts (e.g. the platform's quiz JSON, the82analysis script).8384- The prose documents the data-file schemas; this doubles as the study's85 code book.86- Instrument definitions and their analysis share constants (e.g. item87 titles as result-file column keys) so they cannot drift apart —88 ideally in the same source file, side by side.89- **Uniform instruments are generated, not hand-written.** When the90 items share one form (a validated questionnaire: twenty items, the91 same five responses), do not tangle the platform's JSON directly:92 state the instrument once — titles, items, response anchors,93 instructions — in a constants chunk, tangle a small generator that94 unfolds it into the platform files, and have the analysis program95 include the *same* constants chunk (titles find the reports, anchor96 texts map answers back to scores). Reference: vt-debug's `rspq.nw`97 (`make_rspq.py` + `analyze_rspq.py`).98- Cross-reference both ways: the method section points to the appendix99 program, the appendix points back to the sections that motivate each100 piece.101- **End-to-end automation, both directions.** The programs reach into102 the platform themselves: they *create* the instruments (e.g.103 `canvaslms quizzes create`) and they *fetch* the results back (e.g.104 the student-analysis report via the platform CLI's own importable105 machinery) — course names and instrument titles are known constants,106 so nothing is clicked or downloaded by hand. Where a fetch cannot be107 automated yet, mark it XXX with a tracking issue rather than settling108 for a manual step silently.109- **LLM-assisted coding, human-verified.** For open-text answers that110 need qualitative coding, the analysis program pre-codes them with an111 LLM (the `llm` package; prompt states the coding scheme, answers in112 JSON) and writes the suggestions into columns *separate from* the113 human coder's verified codes — the sheet always shows which is which,114 and the human's codes are the data.115- Build mechanics (article-only noweb.sty, Makefile rules, tangle116 recipes, the syntax-highlighted weave): latex-writing's117 `references/dual-beamer-article.md` section "Literate-program118 appendices", and the literate-programming skill for the standard119 tominted recipe.120- Validate tangled artifacts in the round that creates them (JSON parses,121 Python compiles, quiz validators pass) — and test instrument creation122 end to end against a sandbox course before the real one.123124## Review rounds125126A draft iterates in review rounds; each round is one atomic unit and lives127on **its own branch with its own PR**. Name both after the draft version128the round *produces* — branch `review-round-vN`, PR to the default branch129titled `"Review round: draft vN (YYYY-MM-DD)"` — so branch, PR, commit130message and reMarkable name all carry one identifier (the round that131processes v48's comments and uploads v49 is `review-round-v49`; round132counts and draft versions diverge, so never number by round):1331340. Open the round: branch `review-round-vN` off the default branch. The135 round's work happens here; the PR opens when the round's draft is136 uploaded.1371. Read all annotated pages of the previous draft (remarkable skill:138 `content_type=annotations` to list the pages, `render_merged` images to139 read the handwriting).1402. Interpret every comment; apply all edits of the round.1413. New literature needs discovered in a round go through backing-claims142 (find, verify, provenance block) and into the search-protocol appendix143 **in the same commit**.1444. Rebuild all outputs; verify: zero errors, no unresolved references,145 restatement counts unchanged where expected.1465. **One commit per round**, without asking; the commit message lists the147 round's changes and names the draft version it produces (`"This commit148 is the version uploaded to reMarkable as draft YYYY-MM-DD, vN"`), so149 every uploaded draft maps to exactly one commit. **Commit at upload150 time** — never upload a draft whose source is uncommitted. **Push after151 committing** — the paper repo and, when skills changed, the skills repo152 (mind that the first push of a fresh repo needs `git push -u origin153 <branch>`; a GitHub repo that only ever received issues counts as154 fresh).1556. Upload the new draft as `"<Title> (draft YYYY-MM-DD, vN)"` with N156 incremented.1577. Open the PR (`gh pr create`), listing the round's changes; use158 `closes #N` for issues the round resolved, so merging closes them.159 Merging the PR ends the round; the next round starts at step 0 with a160 new branch and PR.161162## Cite the principle wherever the argument is made163164When a passage argues from a theoretical principle the paper rests on — the165design rationale of an instrument item ("a test of discernment must not166point out the aspect"), the wording of a stem, a coding or analysis choice —167cite the principle's source *in that passage* (e.g. `\autocite[p.~91]{NCOL}`),168not only where the principle was first introduced. The citation is the169support for the argument: a reader of an appendix paragraph does not carry170the introduction's citation with them, and a reviewer sees an unsupported171claim. This holds for every instance — each item rationale that invokes the172principle, each stem redesign in a review round. "Already cited earlier in173the paper" is not a reason to omit it; repeating the same key and page is174correct, not redundant. (Verification per backing-claims happens at the175first use; later uses of the same verified claim reuse the key and page.)176177## Open questions and pending decisions178179- Mark open decisions with `% XXX` and deferred work with `% TODO` in the180 source, stating the alternatives and what resolves them; resolve or181 carry them forward consciously each round — never silently drop one.182- **Mirror them as GitHub issues** whenever the paper repository has a183 GitHub remote (`git remote -v`). This is standing authorisation: create184 the issues with `gh issue create` without asking. Conventions:185 - One issue per XXX/TODO item; the title states the decision or task,186 the body gives the file and section, the context, the alternatives,187 and what resolves it.188 - Annotate the source comment with the issue number — `% TODO(#12): ...`189 — so source and tracker stay linked.190 - Per round: new XXX/TODO items get new issues; items resolved in the191 round get their issues closed (`gh issue close N --comment ...`) in192 the same round, referencing the commit.193 - An item tracked elsewhere too (e.g. a `nytid todo` for work the194 author must do personally) still gets the issue; note the cross-link195 in both.196- Anonymise course/institution details before submission (keep a `% TODO`197 at the top of the method section until done).198199## Checklist (per round)200201- [ ] Every contribution names its research question202- [ ] Methodological questions separate from substantive ones203- [ ] Each question restated in method overview (with mode of answer) and204 in conclusions (with answer)205- [ ] Instruments motivated at their chronological place206- [ ] Questionnaires and analyses exist as literate appendix programs;207 tangled artifacts validated208- [ ] New citations verified and searches documented (backing-claims)209- [ ] Every argument from a theoretical principle cites its source where210 the argument is made, not only at first mention211- [ ] XXX/TODO items mirrored as GitHub issues (new ones opened, resolved212 ones closed) when the repo is on GitHub213- [ ] Both outputs build clean; committed as one round; new draft uploaded