sciwrite-manuscript

6 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

• skills/sciwrite-manuscript/SKILL.md8.7 KB85df5e60ebc3upstream ↗

  ---
  name: sciwrite-manuscript
  description: >
    Structure a scientific paper section by section — tables and figures, Results,
    Methods, Introduction, Discussion, Abstract — following Stanford's Writing in
    the Sciences. Use this skill whenever someone is writing, drafting, planning,
    restructuring or reviewing any part of a research paper, journal article,
    conference paper or thesis chapter: "help me with the introduction", "how do I
    structure the discussion", "is my abstract missing anything", "my results
    section is too long", "what order should I write the sections in", "does this table
    look right", "where should the limitations go". Also use it when someone asks
    what belongs in a given section, or which verb tense a section takes. Use it
    together with sciwrite-prose, which handles sentence-level editing once the
    structure is settled. Do NOT use it for grant proposals or review articles
    (sciwrite-proposals) or for lay summaries and press material
    (sciwrite-outreach).
  ---
  
  # Structuring a scientific manuscript
  
  A paper is not written in the order it is read. This skill covers what belongs in
  each section, in what order to build them, and how to tell whether a draft
  section is doing its job.
  
  Answer in whatever language the user writes to you in; course examples stay in
  their original English.
  
  ---
  
  ## The writing order
  
  Build the manuscript in this sequence. It is not arbitrary — each step makes the
  next one easy, and skipping ahead is why people find writing painful.
  
  1. **Tables and figures.** Not shells or rough drafts: a finished, polished set.
     They contain the story of the paper, and until you know what that story is you
     cannot frame anything else.
  2. **Results.** Falls straight out of the tables and figures.
  3. **Methods.** Could be written at any time — it is a play-by-play of what you
     did — but it sits naturally here.
  4. **Introduction.** Written after the story is nailed down, because only then do
     you know how to frame the question.
  5. **Discussion.** The hardest and most open-ended; easier once everything else
     exists.
  6. **Abstract.** Always last. *Abstract* means *to pull out*, and you are pulling
     from sections that now exist.
  
  When someone asks "where do I start", the answer is almost always the tables and
  figures, even if they came expecting to talk about the introduction.
  
  ---
  
  ## What each section owes the reader
  
  Keep this table in mind; go to `references/sections.md` for the full treatment of
  whichever section is actually on the table.
  
  | Section | Its one job | Shape | Voice |
  |---|---|---|---|
  | Tables & figures | carry the story; stand alone | one clear point each, progressing | — |
  | Results | summarise the tables at a *higher level* | trends and relationships, table cited in parentheses | active |
  | Methods | be the recipe | subsections; diagrams where possible | passive fine, jargon fine |
  | Introduction | set up one question | cone: known → unknown → aim → approach | active |
  | Discussion | answer that question, then broaden | inverted cone: answer → context → limitations → so what | active |
  | Abstract | stand alone | background → aim → methods → key results → conclusion → implication | active |
  
  **Verb tense, one rule for all of them.** Past tense for completed actions — the
  experiments, the analyses, what you and others found. Present tense for what is
  still true as the reader reads: *Figure 1 shows*, *the data suggest*, *the
  findings confirm*. Both appear in the same paragraph routinely.
  
  ---
  
  ## Reviewing a draft section
  
  Read the section against the checks below before doing any sentence-level work —
  a beautifully edited Results section that recites the table is still wrong.
  
  **Results.** Is it reading the table aloud, number by number? That is the
  signature failure. Does it waste a sentence saying *Table 1 shows the
  characteristics of the groups* instead of launching into the finding? Does it
  justify statistical choices that belong in Methods, or interpret findings that
  belong in Discussion? Is the treatment-versus-control comparison foregrounded?
  Are negative results reported?
  
  **Methods.** Could someone replicate this? Is it broken into subsections a skimmer
  can navigate? Is there a protocol or flow that would be clearer as a diagram or
  table? Is the ethics statement present, if needed?
  
  **Introduction.** Count the paragraphs — more than five means it has drifted into
  a literature review. Is there an explicit statement of aim or hypothesis, in
  findable words? Does it review the *specific link* being studied, or the two
  topics separately? Does it summarise prior work at a high level, or walk through
  studies one by one? Does it leak results or implications?
  
  **Discussion.** Does the first sentence answer the question the introduction
  asked? Does it start with limitations (it should not)? Does it discuss things
  that were never measured? Are the limitations specific to *this* study, or
  boilerplate that would fit any paper? Does the last paragraph restate the finding
  and leave a take-home message? Does anyone outside the immediate field learn why
  this matters?
  
  **Abstract.** Does it stand alone? Does it carry the implication sentence — the
  *why should I care* — or stop at the conclusion? Does it use the same explicit
  aim phrasing as the introduction? Do its numbers match the body?
  
  **Tables and figures.** Three horizontal rules and no vertical ones? Units on
  every variable? Significant figures the measurement actually supports? Acronyms
  defined inside the table or legend? Does each one make a single clear point? Are
  significance markers unambiguous about which comparison they refer to? Is the
  same data presented twice, once as a table and once as a figure?
  
  ---
  
  ## Tools
  
  ```bash
  # The scripts ship in sciwrite-prose/scripts/. Find that skill wherever it was
  # installed: plugin, `npx skills add` (project or global), or a manual copy.
  SCIWRITE=$(for d in "${CLAUDE_PLUGIN_ROOT:-.}/skills" .claude/skills .agents/skills \
                      ~/.claude/skills ~/.agents/skills; do
    [ -f "$d/sciwrite-prose/scripts/prose_audit.py" ] && { (cd "$d/sciwrite-prose/scripts" && pwd); break; }
  done)
  
  python "$SCIWRITE/extract_text.py" paper.tex
  python "$SCIWRITE/extract_text.py" paper.tex --section introduction
  python "$SCIWRITE/numeric_consistency.py" paper.tex
  python "$SCIWRITE/keyword_consistency.py" paper.tex
  ```
  
  If `$SCIWRITE` comes back empty, the sciwrite-prose skill is not installed: do
  these checks by reading, and tell the user that
  `npx skills add dvdsosa/scientific-writing-skills` adds the scripts.
  
  `extract_text.py` maps the sections of a `.tex`, `.docx` or `.md` file, so you
  can pull the Discussion without anyone pasting it. Run the consistency checks
  whenever a whole manuscript is in play: numbers that disagree between abstract
  and body, or a group renamed between Methods and Results, are what a reviewer
  notices first and what an author never sees.
  
  ---
  
  ## Helping someone write a section from scratch
  
  Ask for the material before offering structure. For an introduction you need to
  know what is established, what the gap is, and what they asked — and it is common
  that the gap has not been articulated yet, in which case that is the real work
  and the writing is easy afterwards.
  
  For a Results section, ask for the tables and figures. If they do not exist yet,
  say so plainly: writing Results before the figures are settled means writing it
  twice.
  
  Draft in their voice, not a generic one, and follow the prose rules from
  `sciwrite-prose` as you write — active voice, no throat-clearing, keywords
  repeated exactly.
  
  ---
  
  ## Output
  
  For a section review:
  
  ```
  ## <Section> review
  
  <Two or three sentences: does this section do its job, and what is the single
  biggest structural problem?>
  
  ### Structure
  <Against the checks above. What is missing, what is in the wrong section,
  what order the paragraphs should be in.>
  
  ### Specific fixes
  <Original → revision, for the passages that carry the structural problem.>
  
  ### Consistency
  <Numbers, terminology, acronyms — only if there is something to report.>
  ```
  
  When the section is sound, say so and move to prose-level work rather than
  inventing structural objections.
  
  ---
  
  ## Reference files
  
  | File | Read it when |
  |---|---|
  | `references/sections.md` | working on any specific section — the full rules, with worked examples per section |
  | `references/tables-figures.md` | building or reviewing tables and figures; deciding table vs figure |
  | `references/worked-examples.md` | you want a model of a good section, or of the same section done badly |
  | `references/oceanography-sections.md` | the paper reports ocean transports, hydrographic sections or cruise data |
  
  For sentence-level editing once the structure holds, use **sciwrite-prose**. For
  deciding how to spend the writing time in the first place, use
  **sciwrite-process**.
  

• skills/sciwrite-manuscript/references/oceanography-sections.md5.7 KB7c7ad799fa07upstream ↗

  # Section-level patterns in physical oceanography
  
  The course teaches IMRaD with biomedical examples: a trial, a cohort, a dose.
  Observational oceanography keeps the same skeleton but fills it differently —
  the "subjects" are cruises and sections, the "intervention" is usually nothing,
  and the reader's first question is *how confident are you in that number?*
  
  **Provenance:** the structural rules come from the course. The example text
  below was written for this file to show the pattern; no sentence is taken or
  adapted from a published paper.
  
  ---
  
  ## What changes, section by section
  
  | Section | Biomedical default | Oceanographic equivalent |
  |---|---|---|
  | Methods opens with | study design, population | the cruises: dates, ship, section line, station spacing |
  | The "sample" is | patients enrolled | stations occupied, and the years they were occupied |
  | Randomisation and blinding | central to validity | absent — validity rests on the inverse model's constraints |
  | The headline number | effect size with CI | transport in Sv with its uncertainty |
  | The rival explanation | confounding | aliasing of a seasonal or eddy signal by a one-off snapshot |
  
  Everything else — one idea per paragraph, the upshot first, keywords identical
  across sections — is unchanged.
  
  ---
  
  ## 1. Methods: the cruise paragraph
  
  Reviewers check reproducibility here first. The order that works:
  
  1. **The section.** Where it runs, which line designation (A05, P06), station
     spacing, and where spacing was tightened.
  2. **The cruises.** Dates, ship, and which occupation is new versus reanalysed.
  3. **The instruments.** CTD, lowered and shipboard ADCP, with calibration and
     accuracy figures.
  4. **The model.** Layer definitions, the constraints imposed, and — critically —
     what the reference level is and why.
  5. **The uncertainty.** How the error bars were produced.
  
  The reference level deserves its own sentence. It is the single assumption a
  sceptical reader will attack, and burying it inside a list invites the attack.
  
  > **Thin.** An inverse box model was applied to the hydrographic data.
  >
  > **Reproducible.** We applied an inverse box model with eleven neutral-density
  > layers, conserving mass overall and within each layer, and referenced the
  > initial geostrophic velocities to the deepest common level. Layer boundaries
  > follow [ref, Table 1].
  
  ---
  
  ## 2. Results: transports, not tables read aloud
  
  The commonest defect in this literature is a Results section that walks the
  reader down a column of numbers already printed beside it.
  
  **Report:** the pattern, its magnitude, whether it exceeds the uncertainty, and
  where it sits relative to earlier occupations.
  
  **Do not report:** every value in the table; the fact that a table exists; the
  same number in text, table and abstract in three different precisions.
  
  > **Recital.** The upper-layer transport was 16.3 ± 1.2 Sv in 2003 and
  > 17.1 ± 1.4 Sv in 2011 (Table 3).
  >
  > **Result.** Upper-layer transport increased by 0.8 Sv between occupations, well
  > within the combined uncertainty of the two estimates (Table 3).
  
  Significant figures travel with the uncertainty. `16.34 ± 1.2 Sv` claims a
  precision the error bar denies; write `16.3 ± 1.2`. The number in the abstract
  must be the number in the table.
  
  ---
  
  ## 3. Discussion: open with the answer, not the caveats
  
  A discussion that opens with limitations tells the reader the authors do not
  believe their own result. Limitations belong after the interpretation, and each
  one should be paired with what it does and does not affect.
  
  The field-specific limitation that must appear: **a hydrographic section is a
  snapshot.** If the analysis rests on two occupations a decade apart, say plainly
  that interannual and eddy variability cannot be separated from any trend. A
  reviewer will raise it; raising it first is cheaper.
  
  > **Weak.** Our results should be interpreted with caution because of the limited
  > number of cruises.
  >
  > **Specific.** Two occupations a decade apart cannot separate a trend from
  > interannual variability. The 0.8 Sv change we report is therefore an upper
  > bound on any secular signal, not evidence of one.
  
  ---
  
  ## 4. Introduction: narrow to the gap, do not survey
  
  The pull towards a general review of the overturning circulation is strong and
  should be resisted. The funnel:
  
  1. Why this circulation matters — two or three sentences, not two paragraphs.
  2. What repeat sections have established at this latitude.
  3. **The gap**: which years are missing, which layer is unconstrained, which
     disagreement between estimates is unresolved.
  4. What this paper does about it.
  
  If the introduction could preface any paper about the same basin, it is a review,
  not an introduction.
  
  ---
  
  ## 5. Abstract: the numbers a reader will quote
  
  For a transport paper the abstract has to carry the headline transports with
  their uncertainties, the years compared, and the one claim the paper defends.
  Readers cite abstracts; make the citable numbers correct and identical to the
  table.
  
  Checklist before submission:
  
  - [ ] Every number in the abstract appears in the body with the same precision.
  - [ ] Layer names match the Methods definitions exactly.
  - [ ] The section line and the years are both stated.
  - [ ] Any acronym in the abstract is expanded there, not only in the body.
  
  ---
  
  ## 6. Tables and figures
  
  - A **station map** is not optional. Geometry described in prose is geometry the
    reader reconstructs wrongly.
  - A **transport table** is read across occupations, so occupations belong in
    columns and layers in rows.
  - **Uncertainties belong in the table**, not only in the text. A transport
    without its error bar is not a result.
  - Colour scales for velocity sections must be **diverging and centred on zero**,
    or the reader misreads the sign of the flow.
  

• skills/sciwrite-manuscript/references/sections.md11 KB893e9ccbfa6eupstream ↗

  # The sections, one by one
  
  Source: modules 5.2, 5.4, 5.5, 5.7, 5.8. Further reading the course recommends:
  Thomas Annesley's series in *Clinical Chemistry* (free online, not chemistry-
  specific), and Mimi Zeiger, *Essentials of Writing Biomedical Research Papers*.
  
  ---
  
  ## Verb tense — one rule for the whole manuscript
  
  **Past tense** for completed actions: the experiments, the analyses, what you
  found, what other studies found.
  
  > *We found that… · The average reaction time was… · Miller et al. found…*
  
  **Present tense** for assertions that are still true when the reader reads them:
  what a table or figure shows, what the data suggest, what you believe.
  
  > *Figure 1 shows… · Table 1 gives… · The findings confirm… · The data suggest…*
  
  This holds in Methods, Results and Discussion alike. Both tenses routinely appear
  in one paragraph, and that is correct:
  
  > *Information was available for 7,766 smokers. Of these, 1,216 were classified
  > as hardcore smokers. **Table 1 gives** the characteristics of…*
  
  ---
  
  ## Results
  
  Write this immediately after the tables and figures; it falls straight out of
  them.
  
  **The one big mistake: reading the table aloud.** Because Results follows from
  the tables, there is a pull to walk the reader through every number in order.
  That is not what the section is for.
  
  > *The mean age of the bad witches was 45 ± 5, and the mean age of the good
  > witches was 36 ± 6. Gender was similar between the groups with 85 % female in
  > the bad witches and 83 % female in the good witches…*
  
  The reader has the table. Your job is the higher-level summary: point out simple
  relationships, describe big-picture trends, refer to the table for the detail.
  
  > *The witches were on average lean and predominantly female (Table 1). Bad
  > witches were significantly older, had higher blood pressure, exercised less,
  > and were more likely to smoke than good witches. More bad witches were
  > unemployed, but this difference did not reach statistical significance.*
  
  Note also what is **not** there: a sentence saying "Table 1 shows the descriptive
  characteristics of the groups." That is obvious from the table. Launch into the
  finding and cite the table in parentheses.
  
  **Complement rather than repeat.** If a bar graph has no precise numbers, give
  one or two in the text. If the table gives two means, the text can give the
  percentage difference — *good witches exercised twice as long as bad witches*
  rather than restating 60 and 30 minutes.
  
  **Do highlight the key numbers.** In a placebo-controlled trial of a
  blood-pressure drug, the between-group difference in reduction is the number the
  study exists to produce. That one belongs in the text.
  
  **Other rules:**
  
  - Negative results matter as much as positive ones.
  - With a control group, the treatment-versus-control comparison is the one to
    foreground.
  - Reserve *significant* for statistical significance.
  - Do not mix in Methods. Justify the statistical approach in Methods; in Results,
    say what the models revealed. Authors very often explain their model choice
    here, and it confuses the reader.
  - Do not mix in Discussion. Results is what the data show; Discussion is what
    they mean.
  - Subsections with informative headings help when results are long.
  - **Use the active voice.** The fear that every sentence will start with *we* is
    unfounded here: the participants, the measurements, the models and the data are
    all available as subjects.
  
  ---
  
  ## Methods
  
  The recipe. Enough for someone else to replicate the study — while minimising how
  hard that is to read.
  
  **What goes in** (varies by field; this is the shape):
  
  - Materials: reagents, chemicals, cell lines, hardware — with the specifics that
    make them reproducible (pH, temperature, doses, versions, part numbers).
  - Ethics approval, if human or animal subjects. This needs an explicit statement.
  - Experimental protocol.
  - How each variable was measured, and with what instrument.
  - The analysis.
  
  Annesley's checklist is a good pass: **who, what, when, where, how and why**.
  Who maintained the records? What was used? When was it done? Where were things
  kept?
  
  **Three ways to make it readable:**
  
  1. **Subsections with informative headings.** Readers skim Methods hunting for
     one specific thing; headings let them find it. Real examples: *general
     approach / biosafety / isolation of the virus / serologic analysis* — or
     *subjects / experimental protocol / hardware / GPS data processing / wind*.
  2. **Cite rather than repeat.** For a well-known method, or one you described in
     an earlier paper: *as previously described [12]*.
  3. **Diagrams and tables.** A participant flow chart conveys instantly what a
     paragraph of numbers conveys tediously. Complex protocols and dosing schedules
     are usually better as a diagram or table. This is underused.
  
  **Passive voice and jargon are both acceptable here** — this is the one section
  where the rules relax. What was done matters more than who did it; most readers
  skim; and the active voice tends to produce a wall of sentences starting with
  *we*. Mixing passive and active is fine as long as it is not jarring. The active
  voice is equally acceptable if you prefer it; the choice is yours.
  
  ---
  
  ## Introduction
  
  Easier than people expect, because it has a definable format — and shorter:
  **typically three paragraphs, never more than five.**
  
  **The mistake:** treating it as an exhaustive review of the general topic. You
  have read a hundred papers and want to use them. That is not what this section
  is for.
  
  **The introduction is shaped around your specific question.** For a study on
  smoking and breast cancer you do not review breast cancer, and you do not review
  smoking. You review the potential link between the two, and only studies that
  addressed that link. This narrowness is what makes it easy to write.
  
  **The cone — broad to narrow:**
  
  1. **What's known.** Brief context on your specific topic.
  2. **What's unknown.** The gaps and limitations in those previous studies. Why is
     the question still open?
  3. **Your specific question, hypothesis or aim** — stated explicitly, with the
     words: *we hypothesised that*, *we asked whether*, *our aims were*, *we
     investigated*. Reviewers scan for exactly this phrasing to find out what the
     paper is about; make it easy to find.
  4. **Enough of your approach** to show how your study fills those gaps — bigger,
     prospective, a better measure, a population nobody studied.
  
  Roughly one paragraph each for known, unknown, and your study, though authors
  often alternate between known and unknown in the early paragraphs.
  
  **Summarise the literature at a high level.** Not *Jones et al. did a
  case-control study with problems x, y and z, and then Smith et al. did a
  cross-sectional study with problems a, b and c*. Rather: *of nine studies, two
  found an association and seven did not*, and then the shared limitations,
  broadly.
  
  **Other rules:**
  
  - Three *short* paragraphs, not three long ones.
  - Write it for a general audience; save technical detail for Methods.
  - No results, no implications. You are setting the question, not answering it.
  
  A two-paragraph example that does everything (BMJ Christmas issue, academic
  spam): paragraph one is entirely background; then one sentence of unknown — *few
  studies have focused on academic spam*; then the study — *we investigated the
  amount, relevance, content, and suppressibility of academic emails*. Note that
  the four named objectives are the four things the Discussion will answer, in
  order.
  
  ---
  
  ## Discussion
  
  The inverted cone. The introduction ended with the question; the discussion
  starts by answering it, then broadens.
  
  This section gives you the most freedom and is therefore the hardest, and the
  best place to show what you can do as a writer.
  
  **The shape:**
  
  1. **The answer.** First sentence: *We found that…*, answering the question posed
     at the end of the introduction. State explicitly whether the findings are
     novel.
  2. **Key secondary findings**, if any.
  3. **Context.** Possible mechanisms or pathways. How your results fit the
     existing literature — confirming, contrasting.
  4. **Strengths and limitations.** At least one paragraph.
  5. **What's next.** Unanswered questions, what needs confirming.
  6. **So what.** Implication, speculation or recommendation. Why should anyone
     outside your niche care? This is where you make them care.
  7. **Conclusion.** Restate the main finding and give a take-home message.
     Repeating it is deliberate — it is the emphasis.
  
  **Do not start with the limitations.** A real discussion opened *This
  meta-analysis is subject to a number of limitations.* Start with *We found*; bury
  the limitations several paragraphs down.
  
  **Do not travel too far from your data.** Speculation is fine near the end,
  clearly marked. But the main conclusions must report what you actually found, not
  what you hoped to find, and you should not spend paragraphs discussing something
  you did not measure. Waffling because the data did not cooperate is visible from
  outside.
  
  **The limitations paragraph is where good papers separate themselves.** Most
  authors write generic boilerplate that could apply to any study. What impresses a
  reviewer is a limitations section that names the concerns *they* were forming as
  they read:
  
  > The mark of a good paper, for me, is when authors have anticipated my
  > criticisms and concerns… Even if they don't have a good answer for those
  > limitations, just the fact that they recognize them goes a long way to
  > improving my confidence in the study. — module 5.7
  
  So: read your own paper as a hostile reviewer, list what you would attack, and
  address those things specifically. Better still, address them with an analysis —
  one course example excluded participants on confounding medications and reported
  that the results held.
  
  Discussion length in the course's examples ranges from four to seven paragraphs.
  
  ---
  
  ## Abstract
  
  Write it **last**. *Abstract* means *to pull out*: you are pulling snippets from
  the finished paper, which is why it is easy once the paper exists.
  
  **Throw away any abstract you wrote months ago for a conference.** The pull to
  reuse it is strong — it is already written, why waste work? But it was drafted
  before the analysis, tables and story were settled, and it will not fit the final
  paper. Starting the whole manuscript from it is worse. Bin it and start over.
  
  **What goes in:**
  
  1. One sentence of background and motivation.
  2. The research aim or question, in the same explicit phrasing as the
     introduction: *we asked whether*, *we hypothesised that*.
  3. A minimal overview of the methods.
  4. A few key results, a few important numbers. Not many.
  5. A brief conclusion answering the question asked.
  6. **One sentence of implication, speculation or recommendation.** Easy to omit
     and important to keep: it is the *why should I care*, and it is what a
     journalist or a reader outside your field scans for.
  
  Structured abstracts (with mandated subheadings) are easier than free-form ones.
  Either way, the abstract must stand alone — it is the part most people read, and
  often the only part.
  
  Word limits are where your clutter-cutting skills pay for themselves.
  

• skills/sciwrite-manuscript/references/tables-figures.md6.9 KB71e37b55fc52upstream ↗

  # Tables and figures
  
  Source: module 5.1.
  
  Build these **first**, before any prose. The tables and figures contain the story
  of the paper; the writing around them is, in a real sense, advertising for them.
  Editors, reviewers and readers often look at them before reading a word — a
  reviewer typically skims the abstract, then jumps straight to the data to form
  their own judgement before reading the authors' interpretation.
  
  Two consequences. First, they must **stand alone**: a reader must make sense of
  them without going back to the text, so every acronym, unit and experimental
  detail needed to read them lives in the title, legend or footnotes. Second, each
  one must **make a clear point**, and together they must progress through the
  story. If you cannot say what a table's point is, it is not ready.
  
  Use the fewest that tell the story. Never present the same data as both a table
  and a figure.
  
  ---
  
  ## Table or figure?
  
  **Figures** for visual impact; trends and patterns; a quick story; showing all
  the data points rather than summary statistics; showing distribution or range;
  highlighting the single most important result.
  
  **Tables** for precise values, and for many variables at once. A figure does not
  convey a number to the third decimal.
  
  If a figure is turning out complex, that is a signal the data belong in a table.
  A figure that needs study is a failed figure.
  
  ---
  
  ## Table format
  
  **Title** — identifies the specific point of the table, concisely, and says what
  statistics to expect: *Descriptive characteristics of the two treatment groups,
  mean ± SD or n (%)*. Repeat the exact keywords used in the column headings and
  the main text.
  
  **Three horizontal rules. No vertical rules.** One above the column headings, one
  below them, one below the data. This is the convention in almost every journal.
  
  The full-grid table is worth calling out specifically, because it costs more than
  it looks like it should:
  
  > I've reviewed many, many papers over the years. And at some point I noticed
  > that papers with tables like this, with all the grid lines, tend to have lots
  > of problems elsewhere in the paper… So when I flip to the tables and I see all
  > those grid lines, there's a red flag that goes off in my head. I automatically
  > expect that the paper is going to have other problems. I suspect that other
  > reviewers and editors have formed the same association. — module 5.1
  
  Alternating row shading is fine and looks professional, as long as the three
  rules are still the only rules.
  
  **Footnotes** — symbol conventions differ by journal (asterisks, superscript
  letters). Do not guess: open a published paper from the target journal and copy
  what they do. Use footnotes to say exactly which groups were compared and with
  what test, and to define acronyms and experimental details.
  
  ### The five ways tables look unprofessional
  
  1. **Extra grid lines.** As above.
  2. **Misaligned columns.** Especially numbers with decimals. Mixed capitalisation
     between entries. Sloppiness here reads as sloppiness everywhere.
  3. **Too many significant figures.** Statistical software emits BMI to three
     decimals and people paste it in. Report only as many decimals as the
     measurement supports — for clinical or physical variables, usually one.
  4. **Missing units.** *Exercise: 30* — thirty minutes a day? a week? *Age: 45* —
     years, presumably, but months if these are infants. Easy to lose when pasting
     from software output.
  5. **Extra columns.** An "overall" column in a two-group comparison dilutes the
     comparison and can be computed from the other columns anyway. A column of
     exact p-values, where a star and a footnote would flag significance, does the
     same. Extra columns detract from the point.
  
  **Do not reinvent formatting.** Capitalisation, alignment, italics, footnote
  symbols: pull a published paper from your target journal and copy it. Reviewers
  and editors notice tables that look like the journal's own.
  
  ---
  
  ## Figures
  
  ### Three kinds
  
  **Primary evidence** — gels, micrographs, photographs, x-rays, pathology slides,
  oscilloscope captures. These show data quality, and they carry a seeing-is-
  believing weight that no summary statistic does. Video counts too, and carries it
  even more strongly.
  
  **Graphs** — the data visualised.
  
  **Drawings and diagrams** — underused, and powerful. Use them for an experimental
  setup, a participant or data flow, a causal or cycle relationship, a hypothetical
  model, or to give readers a picture of something they cannot see. Information
  that is genuinely visual is tedious in prose and instant in a drawing. In one
  course example, dog-bite and cat-bite locations went into a body diagram instead
  of a table, and both key messages — most bites are on the hands, and cat and dog
  bites differ in location — became visible immediately.
  
  ### Legends
  
  Every figure needs one, because the figure must stand alone: a brief informative
  title conveying the main point; the experimental details a reader needs; symbol,
  line and panel definitions; and the statistical detail — which test, which
  comparison, what the p-values were.
  
  ### Graph types
  
  | Type | Use |
  |---|---|
  | Line graph | trends over time, dose, age — anything increasing or decreasing |
  | Bar graph | comparing groups at one time point or dose; easy to read, quick story |
  | Scatter plot | relationship between two continuous variables; shows every data point |
  | Histogram | distribution of one variable |
  | Box plot | distribution and spread across groups |
  | Survival curve | time-to-event |
  
  Scatter plots deserve their reputation: they show all the data, including the
  variation and non-linearity that summary statistics hide. In the course's
  example, a scatter plot revealed both that one group had far wider variation than
  its mean suggested and that the relationship was curved rather than straight —
  neither visible from a table of means.
  
  ### The trend-line warning
  
  A superimposed line can manufacture a relationship that is not there. In the
  course, the same scatter of unrelated x and y was shown twice, once with a
  downward line and once with an upward line; each time the eye saw a correlation.
  Remove the lines and there is none. Superimpose a fit only when the relationship
  genuinely has that shape.
  
  ### Making graphs easy to read
  
  - Label groups meaningfully instead of using arbitrary symbols. **T** and **C**
    beat filled circles and open triangles, because the reader never has to look
    at the legend.
  - Use colour. The black-and-white photocopy era is over.
  - Put sample sizes on the bars. Readers want *n* and almost never get it.
  - Shade bars; leave nothing at low resolution.
  - If stars mark significance, make it unambiguous which comparison they refer
    to. Ambiguous stars are the single most common defect in published figures.
  - Do not add a bar graph summarising data a line graph already shows. Averaging
    sessions 5–10 into a bar adds nothing that a star on the line graph would not,
    and it clutters the figure.
  

• skills/sciwrite-manuscript/references/worked-examples.md9.5 KB7e588db0ed85upstream ↗

  # Worked examples, section by section
  
  Course examples are marked with their module. Engineering examples were written
  for this plugin to exercise the same patterns in a different register — the rules
  are the course's, the sentences are not.
  
  ---
  
  ## Introduction: the known / unknown / aim skeleton
  
  ### Course example — academic spam (module 5.5)
  
  Two paragraphs. The whole introduction.
  
  > **[known]** *Unsolicited and unwanted (spam) electronic invitations to speak at
  > or attend conferences or to write for or edit journals are a burgeoning aspect
  > of academic life. Colleagues regard such invitations with wry amusement,
  > intense frustration or resignation. Two of us have reviewed travel grant
  > applications from colleagues who received spam invitations to give conference
  > presentations.*
  >
  > **[unknown]** *Few studies have focused on academic spam.*
  >
  > **[this study]** *We investigated the amount, relevance, content, and
  > suppressibility of academic emails.*
  
  The unknown is one sentence. The aim names four things — and those four are
  exactly what the discussion answers, in order. That correspondence is the point.
  
  ### Course example — obesity and cancer mortality (module 5.5)
  
  Alternates known and unknown, which is common:
  
  - known: excess weight raises all-cause and cardiovascular mortality; it matters
    in cancer generally
  - unknown: the magnitude, and which individual cancers
  - known: consistent associations for endometrium, kidney, gall bladder, breast
    (post-menopausal), colon in men
  - unknown: pancreas, prostate, liver, cervix, ovary and blood cancers are scarce
    or inconsistent — *summarised in a single sentence, with no study-by-study walk*
  - why the question is open: few prospective studies, inconsistent categorisation
    of overweight, smoking bias
  - this study: *We conducted a prospective investigation in a large cohort of U.S.
    men and women to determine the relations between body mass index and the risk
    of death from cancer at specific sites.*
  
  Every gap named in the "unknown" is answered by a design feature named in the
  last sentence: prospective, large, BMI rather than arbitrary categories.
  
  ### Engineering version
  
  > **[known]** *Convolutional detectors now run in real time on embedded
  > accelerators, and several vendors ship toolchains that quantise and deploy them
  > automatically [refs].*
  >
  > **[unknown]** *How much accuracy that automated quantisation costs is reported
  > inconsistently: published figures range from under one point to more than eight,
  > across benchmarks that differ in resolution, class balance and backbone.*
  >
  > **[gap in prior work]** *No study has held the deployment target fixed while
  > varying the backbone, so the reported spread cannot be attributed to the
  > quantisation itself.*
  >
  > **[this study]** *We measured post-quantisation accuracy and latency for three
  > backbones on a single Kria KV260 target, using one dataset and one toolchain
  > version, to isolate the cost of automated quantisation.*
  
  Note the shape: the gap is not "nobody has done this", it is "the existing
  numbers cannot answer the question because of how they were produced" — which is
  what makes the study necessary rather than merely new.
  
  ---
  
  ## Results: summary versus recitation
  
  ### Course example — the witches table (module 5.2)
  
  **As written by a student:**
  
  > *The characteristics of the bad witches and the good witches are shown in Table
  > 1. The mean age of the bad witches was 45 ± 5, and the mean age of the good
  > witches was 36 ± 6. Gender was similar between the groups with 85 % female in
  > the bad witches and 83 % female in the good witches. The mean BMI of the bad
  > witches was…*
  
  **Edited:**
  
  > *The witches were on average lean and predominantly female (Table 1). Bad
  > witches were significantly older, had higher blood pressure, exercised less,
  > and were more likely to smoke than good witches. More bad witches were
  > unemployed, but this difference did not reach statistical significance.*
  
  No numbers at all, and nothing is lost — the table has them. The first sentence
  of the original, announcing what Table 1 contains, is deleted entirely.
  
  ### Course example — running during pregnancy (module 5.3)
  
  Here some numbers *do* belong, because this table carries the study's main
  result. The edit keeps four and drops a dozen:
  
  > *70 % of runners ran during pregnancy (n = 77), and almost one-third ran during
  > the third trimester. On average, those who ran during pregnancy greatly
  > curtailed their training — running just 20.3 ± 9.3 miles per week and cutting
  > their intensity to about half of their non-pregnant running effort. Three
  > reported sustaining a running injury while pregnant. In the postpartum period,
  > nearly a quarter waited two or fewer weeks to resume running, and most resumed
  > within two months.*
  
  Two things to notice. *47.9 ± 21 %* became *about half*, because the precision
  was not the point. And *3.9 %, 3 out of 77* became *three*, because three is
  self-evidently a small number.
  
  ### Engineering version
  
  **Recitation:**
  
  > *Table 3 shows the results for the three configurations. The mean latency of
  > configuration A was 12.4 ± 1.3 ms, the mean latency of configuration B was 9.8
  > ± 1.1 ms, and the mean latency of configuration C was 9.6 ± 1.4 ms. The
  > accuracy of configuration A was 91.2 %, of configuration B 93.7 %, and of
  > configuration C 93.9 %.*
  
  **Summary:**
  
  > *Hardware acceleration cut mean latency by roughly a quarter with no loss of
  > accuracy, and the two accelerated configurations were indistinguishable from
  > each other (Table 3). The accuracy gap that matters is between the baseline and
  > either accelerated variant: 2.5 points.*
  
  The one number promoted into the text is the one the study exists to estimate.
  
  ---
  
  ## Discussion: answering the question you asked
  
  ### Course example — low-carb versus low-fat (module 5.7)
  
  The introduction ended with two questions: (a) greater weight loss on a
  carb-restricted diet, and (b) without harming heart health.
  
  Paragraph 1, first sentence, answers (a):
  
  > *We found that severely obese subjects with a high prevalence of diabetes and
  > pre-diabetes lost more weight in a six-month period on a carb-restricted diet
  > than on a fat- and calorie-restricted diet.*
  
  Paragraph 2 answers (b). Paragraph 4 gives the limitations — and gives them well:
  many participants were on lipid-lowering and antihypertensive drugs, which could
  plausibly drive the cardiovascular findings, so the authors re-ran the analysis
  excluding those participants and reported that the result held. Paragraph 6 adds
  the high attrition rate.
  
  Paragraph 7 restates both answers, then adds the caution that keeps the paper
  honest:
  
  > *This study proves a principle and does not provide clinical guidance. Given
  > the known benefits of fat restriction, future studies evaluating long-term
  > cardiovascular outcomes are needed before a carb-restricted diet can be
  > endorsed.*
  
  That last move — refusing to overstate — is what a careful reviewer is looking
  for.
  
  ### How not to open a discussion (module 5.7)
  
  > *This meta-analysis is subject to a number of limitations.*
  
  Start with what you found. The limitations go several paragraphs down.
  
  ### Engineering version, opening paragraph
  
  > *We found that automated eight-bit quantisation costs between 1.1 and 2.4
  > accuracy points on the KV260, and that the spread across backbones is far
  > narrower than the published range suggests. The depthwise-separable backbone
  > lost the most, which we did not anticipate.*
  
  *We found that*, then the answer, then an explicit note that one finding was
  novel or unexpected. Saying which results surprised you is not a weakness; it is
  the sentence a reader remembers.
  
  ---
  
  ## Abstract: pulling from the finished paper
  
  ### Course example — academic spam (module 5.8), structured
  
  - **Background / objectives** — *to assess the amount, relevance, content and
    suppressibility of academic spam invitations to attend conferences or submit
    manuscripts*
  - **Design, setting, participants** — five academics
  - **Main outcome measures**
  - **Results** — *at baseline, recipients received an average of 312 spam
    invitations each month. Unsubscribing reduced the frequency by 39 % after one
    month, but by only 19 % after one year. Overall, 16 % of spam invitations were
    duplicates and 83 % had little or no relevance to the recipients. Spam
    invitations were characterised by inventive language, flattery and exuberance.*
  - **Conclusion** — *academic spam is common, repetitive, often irrelevant and
    difficult to avoid or prevent.*
  
  The results answer the four objectives in the order they were stated. That
  alignment is what makes an abstract feel tight.
  
  ### The missing sentence most abstracts have
  
  The implication. One sentence at the end saying why this matters beyond the
  study. It is the first thing a journalist or an outside reader looks for, and the
  easiest thing to leave out because you are already at the word limit.
  
  ---
  
  ## A whole-manuscript failure mode: numbers that disagree
  
  From module 4.6, and worth keeping in mind because it costs nothing to prevent
  and is expensive to be caught on:
  
  - Methods: *we followed participants for a minimum of two years.*
  - Results: *the average follow-up time was one and a half years.*
  
  Both cannot be true. Whatever the author meant, a reviewer now doubts the whole
  analysis. Same for an abstract that reports different numbers from the body, and
  for a table and a figure that should match and do not:
  
  > If you can't keep track of your dataset, that makes me worry about the whole
  > analysis. — module 4.6
  
  Run `numeric_consistency.py` before submitting.
  

• README.mdupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/dvdsosa-scientific-writing-skills-skills-sciwrite-manuscript.md