Writing & communication

A result nobody can follow does not count, and in practice most readers see the title, the abstract and the figures and nothing else. This section is about writing for that: a structure that gets the contribution across early, figures that carry the argument rather than decorate it, precision about what was shown as against what is merely suggested, and stating the limitations yourself before a reviewer states them for you.

Most readers read three things#

Title, abstract, figures. Write as though that is all anyone will see, because for most readers it is. If the contribution is not clear from those three, it will not be clear at all.

The consequence for the title is the one people resist. A title is not a label for a topic; it is the only sentence most people will ever read of your work, so it should be the claim. Three titles for the same paper, in increasing order of how much they do:

weak     On Chunking Strategies for Retrieval-Augmented Generation

better   A Comparison of Six Chunking Strategies for Retrieval-Augmented
         Generation

strong   Chunk Boundaries Matter More Than Chunk Size

The usual objection is that a claim as a title overstates. It does not, if the claim is the one your experiment supports; what overstates is a claim broader than the evidence, which is a separate problem with a separate fix, below. A title that names the finding also does something quietly useful for you: if you cannot write one, you do not yet know what you found, and that is better discovered before the deadline than after.

Structure#

1. 1.What problem, and why it matters.
2. 2.What has been tried, and what is missing.
3. 3.What you did.
4. 4.What happened, with numbers.
5. 5.What it means, and what it does not.

Each of those has a one-line test, and running the five tests is faster than re-reading the draft. Can a reader say who is worse off because this problem is unsolved? Does the second part name a specific thing that was tried and what it failed at, rather than listing citations? Could a competent stranger reimplement the third? Does the fourth contain a number with an uncertainty attached to it? Does the fifth name a condition under which the result would not hold? A draft that fails one of these fails it in a specific place, which is much easier to fix than a draft that merely feels unclear.

The order matters more than it looks, because it is the order in which a reader grants you credit. A reader who does not accept that the problem is real reads your method as effort spent on nothing. One who accepts the problem but not the gap assumes you have not read the literature. Each part is a precondition for the next being read at all, which is why a paper that is strong in the middle and weak at the start reads as weak throughout.

Figures#

A figure should make its point without the caption, and the caption should make it without the body text. Label axes with units, show variance, and do not truncate an axis to make a difference look larger than it is.

Before any of that comes a harder question: which figure. Most papers have one figure that carries the argument and several that document things, and they are usually given the same size and the same care. Decide which one is load-bearing by asking what a reader would have to see in order to believe your central claim. Make that one first, put it on the first page if the format allows, and design the others to support it rather than compete with it.

Axis truncation deserves a concrete example, because it is usually done innocently. Two methods score 0.71 and 0.78. Plotted from zero, the bars differ visibly and the difference looks like what it is, about a tenth. Plotted from 0.70, the second bar is eight times the height of the first, and a reader skimming carries away an impression of a transformation rather than of seven points. Nothing in the figure is false and the axis is labelled. It is still misleading, and a reviewer who notices will apply that suspicion to every other number you report.

Be precise about the claim#

Overclaimed:  "Our method improves reasoning."

Precise:      "Our method improves accuracy by 3.2 points on
               GSM8K with a 7B model, averaged over five seeds.
               We did not test other model sizes or benchmarks."

Those two are not a pair of options, they are the ends of a ladder, and the job is to find the highest rung your evidence actually reaches and stand on it. Here is one experiment claimed at five strengths, with what each rung would require.

5  "Our method improves reasoning."
     would need several reasoning benchmarks, several model families and
     more than one scale. You ran none of that.

4  "Our method improves mathematical reasoning in language models."
     would need several maths benchmarks and at least two model families.

3  "Our method improves GSM8K accuracy for 7B models."
     would need several different 7B models, and a reason to think the
     parameter count is the thing that matters.

2  "Our method improves GSM8K accuracy for Llama-3-8B by 3.2 points,
    averaged over five seeds (sd 0.6)."
     needs exactly what you ran. This is your rung.

1  "Our method scored 3.2 points higher than the baseline on our run."
     needs nothing, and is too weak: it declines to generalise at all,
     so a reader cannot use it for anything.

The failure that costs most is not writing rung five instead of rung two. It is writing rung five in the abstract and rung two in the results, which most papers with an overclaim actually do. A reviewer reads both, notices the paper contradicting itself, and now has to decide which version the authors believe. That is a much worse position than having claimed too much consistently, because it looks like the broad claim was chosen knowing it was not supported.

That only works if the limitations are real. A limitations paragraph is the easiest place in a paper to perform rigour without having any, and reviewers read hundreds of them, so the generic ones are recognised instantly. Three that appear constantly, and what each becomes when it is meant:

empty   "Our results may not generalise to all settings."
real    "All four collections are English technical documentation.
         We expect the gain to shrink on prose without headings,
         because the method keys on section boundaries."

empty   "Future work could explore larger models."
real    "We tested 7B and 8B models only. The mechanism we propose
         predicts a smaller gain at larger scale, since stronger
         models recover more from a bad chunk; we could not test
         this."

empty   "Our evaluation has some limitations."
real    "Answers were graded by one model-based judge, validated
         against 200 human labels at kappa 0.71. Disagreements were
         concentrated in multi-hop questions, so the multi-hop
         numbers in Table 3 are the least reliable in the paper."

The test for a limitation is whether it costs you something to write. If naming it does not narrow any claim you made, it is decoration. The three above each give something away: the first restricts the domain, the second concedes that the effect may be an artefact of scale, and the third tells a reader which table to trust least. That is why they buy credibility, and why the empty versions buy none.

The same discipline at work#

This transfers directly to engineering. A design document that states the problem, the options, the choice and its limitations is persuasive for the same reasons, and technical influence largely runs through writing.

The mapping is close enough to write down. A design document is the same five parts with different names, and it has the same failure mode: most of them are written as advocacy for a decision already made, which senior readers detect and discount.

paper                          design document

problem, and why it matters    what is broken now, and what it costs
                               per week in money, incidents or hours

what has been tried            what we do today, and the specific
                               thing it cannot do

what you did                   the proposal, concrete enough to
                               estimate

what happened, with numbers    the evidence: a prototype, a
                               measurement, a load test, a cost model

what it means and does not     what this does not fix, what we are
                               betting on, and what would make us
                               reverse it

The other borrowing worth making is the alternatives section. A paper that does not say why the obvious approach fails reads as unaware of it; a design document that does not say why the boring option was rejected reads as someone who wanted to build the interesting one. Write the two or three alternatives you did not choose, with one sentence each on the condition under which each would have been right. A reader who agrees with one of those conditions will now tell you, which is the entire point of circulating the document before building anything.

A first draft is not the work, it is the raw material. This section is about what turns one into something people can follow: revising in passes rather than trying to fix everything at once, cutting the third of the draft that is hedging and restatement, and asking for feedback in a form that produces something usable — have someone state your main point in one sentence and see whether it is the one you meant. It also covers replying to review without either capitulating or arguing.

Revise in passes#

1. 1.Structure: is the argument in the right order, and is the contribution clear from the first page?
2. 2.Paragraphs: does each one make a single point?
3. 3.Sentences: cut every word that does not carry meaning.
4. 4.Figures: does each one make its point without the text?

Doing them in separate passes is not fussiness. Structure and sentences are different jobs and they interfere: an hour spent polishing the wording of a paragraph makes you unwilling to delete it, and the structural pass is mostly deletion. Fix the order first, while everything is still cheap to throw away.

One paragraph, before and after#

Advice about clarity is easy to agree with and hard to apply, so here is a paragraph of the kind that appears in real first drafts, followed by the same content fixed, followed by a list of exactly what changed. Read the first one at the speed you would read a paper you did not choose.

BEFORE

In this work, we propose a novel approach for the chunking of documents
in the context of retrieval-augmented generation systems. It is well
known that the way in which documents are split into chunks can have a
significant impact on the overall quality of the resulting system, and a
number of different strategies have been proposed in the literature to
address this issue. In order to investigate this further, we performed a
comprehensive set of experiments in which we evaluated a variety of
different chunking strategies across several different document
collections. Our results demonstrate that our proposed approach is able
to achieve improved performance relative to the baselines that we
considered, which we believe suggests that chunk boundaries may be an
important consideration for practitioners.

AFTER

Splitting documents on their section boundaries retrieves better than
splitting them every 512 tokens. We compared six chunking strategies on
four document collections, holding the retriever and the generator
fixed; boundary-aware chunking scored 8.4 points higher on answer
accuracy, averaged over five seeds. The gain was largest on long
structured documents and absent on short unstructured ones.

Seven things changed, and it is worth naming them separately because they are separate habits. One: the result moved to the first sentence, so the reader knows the finding before the method. Two: a novel approach became the thing itself, splitting on section boundaries, which is both shorter and checkable. Three: a significant impact became 8.4 points. Four: the stack of hedges at the end — we believe, suggests, may be — became a statement, with the honesty moved into a condition instead. Five: the quantity words, comprehensive, a variety of, several different, became quantities: six, four, five. Six: three phrases of throat-clearing were deleted outright. Seven: a limitation was added, which makes it longer and better.

Most of that is mechanical enough to count. The checks below are crude on purpose — a fixed list of stock phrases and hedges, the word count, and how many digits the paragraph contains — and crude is the point, because a draft that scores badly here is badly written for reasons the author can see without an argument about taste.

BEFORE = """In this work, we propose a novel approach for the chunking of documents
in the context of retrieval-augmented generation systems. It is well known that the
way in which documents are split into chunks can have a significant impact on the
overall quality of the resulting system, and a number of different strategies have
been proposed in the literature to address this issue. In order to investigate this
further, we performed a comprehensive set of experiments in which we evaluated a
variety of different chunking strategies across several different document
collections. Our results demonstrate that our proposed approach is able to achieve
improved performance relative to the baselines that we considered, which we believe
suggests that chunk boundaries may be an important consideration for practitioners."""

AFTER = """Splitting documents on their section boundaries retrieves better than
splitting them every 512 tokens. We compared six chunking strategies on four document
collections, holding the retriever and the generator fixed; boundary-aware chunking
scored 8.4 points higher on answer accuracy, averaged over five seeds. The gain was
largest on long structured documents and absent on short unstructured ones."""

HEDGES = ["may", "might", "could", "suggests", "we believe", "potentially",
          "somewhat", "relatively", "arguably", "appears to", "tends to"]
FILLER = ["in this work", "it is well known that", "in order to", "the way in which",
          "in the context of", "a number of", "a variety of", "comprehensive",
          "novel", "several different", "is able to", "the resulting",
          "overall", "in the literature", "to address this issue"]

def report(name, text):
    low = " ".join(text.split()).lower()
    words = len(low.split())
    digits = sum(c.isdigit() for c in low)
    h = [p for p in HEDGES if p in low]
    f = [p for p in FILLER if p in low]
    print("%-6s words %3d   digits %2d   hedges %d %s" % (name, words, digits, len(h), h))
    for i in range(0, len(f), 3):
        print("       filler:" if i == 0 else "              ", ", ".join(f[i:i + 3]))

report("before", BEFORE)
report("after", AFTER)

# before words 125   digits  0   hedges 3 ['may', 'suggests', 'we believe']
#        filler: in this work, it is well known that, in order to
#                the way in which, in the context of, a number of
#                a variety of, comprehensive, novel
#                several different, is able to, the resulting
#                overall, in the literature, to address this issue
# after  words  57   digits  5   hedges 0 []

Cut#

First drafts are almost always too long. Hedges, restatements and throat-clearing accumulate. Cutting a third of a draft usually makes it clearer, not thinner.

The third that goes is not evenly distributed, and knowing where it hides makes the pass fast. These replacements are close to mechanical, and doing them in one sweep before you think about anything else usually removes a fifth of the text.

what you wrote                              what it becomes

It is important to note that X              X
In order to Y                               To Y
Due to the fact that Z                      Because Z
We performed experiments in which we        We compared
   evaluated
has a significant impact on                 changes it by <number>
demonstrates improved performance           scored <number> higher
a number of / a variety of                  six
It is well known that X. [X is your         delete the sentence
   own field's common ground]
As mentioned in Section 3, ...              delete; they can read Section 3
In this paper, we ...  [in the body]        delete; they know where they are

Three things are worth protecting from the cutting pass, because they look like padding and are not. The sentence that says what the result does not show. The sentence that dispatches the obvious alternative a reader is currently thinking of. And the definition of a term you are using in a slightly non-standard way. Each of those is a sentence that prevents a misreading, and the cost of a misreading is a reviewer who stops believing you.

Useful feedback#

Ask a specific question rather than for general comments. Ask someone to state your main contribution in one sentence after reading it. If they cannot, or state something else, the draft is not doing its job regardless of how the prose reads.

Any question of the form what do you think invites the reader to look for wording problems, because wording is what is easy to comment on. These five are worth asking instead, and each one fails loudly rather than quietly.

1. 1.In one sentence, what did this paper find? If the answer is not your main claim, the abstract has failed, and nothing downstream of it will be read charitably.
2. 2.Which claim did you least believe? This gets you the weakest link rather than the most visible one, and it is the claim a reviewer will attack.
3. 3.Where did you stop and re-read? Do not ask them to explain why. The location is the finding; the diagnosis is your job.
4. 4.What did you expect to be in here that was not? This catches the missing baseline and the missing ablation, which are the two rejections you cannot fix after submission.
5. 5.If you had to cut a page, which page? A reader who can answer this instantly has told you which section is not carrying its weight.

Ask different questions of different readers. Someone inside your area should be asked question two and question four, because those need the literature. Someone outside it should be asked question one and question three, because they will get confused where a real reader gets confused, and an expert will silently repair your sentences as they read.

Responding to review#

A review is a list of things that at least one careful reader thought after reading your draft, and a response is a document with one job: to let a busy editor see, without re-reading the paper, what changed. Here is a real-shaped review comment and two responses, because the interesting case is not the one where the reviewer is right.

REVIEWER 2

The paper claims boundary-aware chunking is better, but Table 2 shows the
improvement is within the standard deviation on two of the four collections.
The authors should run more seeds. Additionally, the comparison to
fixed-size chunking is unfair, since the fixed-size baseline uses no
overlap, which is not standard practice.

RESPONSE TO R2.2 (the overlap baseline) -- we agree

You are right, and we have changed it. We reran fixed-size chunking with
20% overlap, the default in both libraries we cite, on all four
collections. The gap narrows from 8.4 to 5.9 points and the ordering is
unchanged. Table 2 and the abstract now report the overlapping baseline;
Appendix C keeps the original numbers. This was the correct baseline and
we should have used it.

RESPONSE TO R2.1 (two collections inside the standard deviation) -- we disagree

We agree with your reading of Table 2 and have narrowed the claim: the
abstract now says the gain is largest on long structured documents and is
not distinguishable from zero on the two short unstructured collections
(Section 5.3, revised).

We have not run more seeds, and we would rather say why than quietly not
do it. Our five seeds vary only the chunker's tie-breaking; the
collections and the retriever are fixed. More seeds would therefore
narrow the interval around the same point estimate, and would not address
the question you are raising, which is whether the effect exists on short
documents at all. The experiment that would address it is a fifth
collection of short unstructured documents, which we did not have. We
have added this to the limitations (Section 7) and named it as the
experiment that would settle the question.

Notice what the second response does not do. It does not argue that the reviewer misread the table, and it does not comply in order to be agreeable — running more seeds would have cost a week and produced a tighter interval around a result that was never in dispute. Conceding the claim while declining the method is a stronger position than either, and it is available far more often than people use it, because it rests on knowing exactly what your own experiment varied.

Three failures lose a reviewer outright, in descending order of how often they happen. Agreeing warmly and changing nothing, which is visible immediately and reads as bad faith. Answering a question adjacent to the one asked, which reads as evasion whether or not it was. And arguing about whether the reviewer should have been confused, which is the one that feels most justified at the time and is never worth it: their confusion is data about the text, and it is the only data of that kind you will get before publication.

Every section of a paper has a job, and each has a shape that reviewers are used to. Following the shape is not a lack of imagination; it is what lets a reader find what they need in the two minutes they will actually give you. This section gives the shape for each part, with the words written out, because the advice to write a clear abstract is useless and the five sentences it should contain are not.

The abstract, in five sentences#

One sentence each: the context everyone accepts, the specific problem with it, what you did, what you found with a number in it, and what it means. Nearly every good abstract is this, and reading a few with the pattern in mind makes it hard to unsee.

1. context      Retrieval-augmented systems are now standard for
                answering questions over private documents.
2. problem      Their quality depends heavily on how documents are
                split into chunks, and this choice is usually made
                by guesswork.
3. what you did We compare six chunking strategies across four
                document collections, holding the retriever and the
                generator fixed.
4. what you     Chunking on section boundaries beats fixed-size
   found        chunking by 8.4 points of answer accuracy, and the
                gain is largest on long structured documents.
5. what it      Chunk boundaries matter more than chunk size, which
   means        is the parameter most systems expose.

The introduction, in four paragraphs#

The introduction is the abstract with room to breathe, and it has four jobs in a fixed order. First, the world as it is, ending at the gap. Second, why the gap is hard, which is where you dispatch the obvious solutions a reader is already thinking of. Third, what you did and what you found, stated plainly and early — do not save the result for the end, because a reader who has to wait for it will not. Fourth, your contributions as an explicit list.

paragraph 1   what is true and accepted, narrowing to the gap
paragraph 2   why the obvious fixes do not work
              ("one could simply X, but X fails because ...")
paragraph 3   what we do, and the headline number
paragraph 4   contributions, as a list a reviewer can check off

A method section someone can reimplement#

The test is not whether the method is described. It is whether a competent stranger with your paper and no access to you could produce your numbers. That is a much higher bar, and it is met by including the things that feel too small to mention, because those are exactly the ones that get omitted.

• Every hyperparameter, including the ones you did not tune and the ones you left at their defaults.
• The optimiser, the schedule, the warmup, and the effective batch size after any gradient accumulation.
• Preprocessing in full: tokenizer, normalisation, filtering, deduplication, and what you did with examples that failed it.
• How the splits were made, and whether anything is grouped or time-ordered.
• Which numbers are single runs and which are averaged, over how many seeds.
• Compute: what hardware, and how long. It tells the reader whether they can attempt this.

Write the method in the order the code runs, not the order you discovered things. The history of how you arrived at the method is interesting to you and is a burden to the reader; if it genuinely matters, it is a paragraph in the discussion.

The practical way to hit the reimplementation bar is to write the method from the code rather than from memory, with the file open. Memory reconstructs the version you intended; the file has the learning rate you actually used after the third run, the filter you added on a Friday, and the one line that reorders the data. Those are precisely the details that separate a reimplementation that reproduces your number from one that does not, and the author is the last person who can tell which of them mattered.

Experiments organised by claim#

The common failure is organising this section by experiment — here is table one, here is table two — which makes the reader assemble the argument themselves. Organise it by claim instead, with each subsection named for something you are asserting and containing the evidence for exactly that.

by experiment (weak)              by claim (strong)
  5.1 Main results                   5.1 Boundary-aware chunking
  5.2 Ablations                          improves answer accuracy
  5.3 Additional experiments         5.2 The gain comes from the
  5.4 Analysis                           boundaries, not the size
                                     5.3 It holds across four
                                         document collections
                                     5.4 It costs 4% more indexing
                                         time, and nothing at query
                                         time

Each subsection then follows the same small pattern: state the claim, say which experiment tests it, give the result with its uncertainty, and say what would have falsified it. That last part is rare and is the single thing that most raises a reader's confidence, because it shows the experiment could have come out the other way.

5.2  The gain comes from the boundaries, not the size

CLAIM       Boundary-aware chunking helps because of where it cuts, not
            because its chunks happen to be longer.
TEST        Fixed-size chunking at the mean boundary-aware chunk length
            (612 tokens), against boundary-aware chunking, same corpus,
            same retriever, five seeds.
RESULT      Fixed-size at 612 tokens scores 61.2 (sd 0.7); boundary-aware
            scores 69.4 (sd 0.6). The 8.2-point gap survives matching
            the length.
FALSIFIED   If matching the chunk length had closed the gap to within
            the seed spread, the effect would have been length all
            along and Section 5.1 would not support the claim it makes.

Figures that stand alone#

Assume every figure will be seen by itself, in a talk, on a slide someone else made, or in a screenshot. It has to work without the body text. That means axis labels with units, a caption that states the finding rather than describing the plot, and error bars whose meaning is given in the caption.

weak     Figure 3: Accuracy versus chunk size.

strong   Figure 3: Boundary-aware chunking (blue) beats fixed-size
         chunking (grey) at every chunk size, and the gap widens on
         longer documents. Shaded regions are 95% intervals over
         5 seeds. n = 2,400 questions.

Limitations, early and specific#

Put limitations where they will be read and make them real ones. A limitations paragraph that says results may not generalise to all settings is worse than none, because it signals the authors know the form without meaning it. Name the specific conditions under which you expect your result to fail — a document type you did not test, a scale you could not reach, a baseline you could not run — and say what evidence would settle it. Reviewers reward this, and, more practically, anyone who finds the limitation themselves after you have concealed it stops believing the rest of the paper.

A project that exists only on your own machine is invisible. This section is about turning one into a short public write-up people finish reading: one idea per post, the result and the figure at the top instead of saved for the end, the code shown rather than described, and the limits stated plainly. Being straight about what your result does not show is what makes a reader trust the part that it does.

Why it matters for you#

A clear write-up of a small project, with code and numbers, shows what you can do and how you think in a way a CV cannot. It gives an interviewer something concrete to ask about, and it keeps working for you after you publish it.

The mechanism is worth understanding, because it changes what you write. An interviewer reading a CV has to take every line on trust and has no way to ask a better question than the one on their sheet. An interviewer who has read four hundred words in which you measured something, found it smaller than you expected and said so, has already seen you reason, and the conversation starts several steps further in. That is bought by the honesty rather than by the size of the result, which is why a careful small post outperforms an impressive vague one.

One idea per post#

The commonest way a good write-up fails is that it contains three findings. Each one dilutes the others, the title can only name one of them, and a reader who would have shared the post cannot say what it was about in the message they would have sent with it. If you have three things, you have three posts, and the second and third are nearly free because the setup is already written.

The test is the same as for a paper: write the title as the finding, and if the title needs an and in it, you have two posts. A post about chunking strategies and embedding models and a cost analysis is a post nobody finishes. A post called Chunk boundaries mattered more than chunk size is one somebody forwards.

The shape of a good post#

1. 1.The finding in the title or first sentence.
2. 2.One figure that shows it.
3. 3.What you did, briefly, with a link to code.
4. 4.What surprised you, and what did not work.
5. 5.What you would try next.

The first item is the one that gets argued about, because the instinct is to build up to the result the way you arrived at it. Resist it. A reader has given you fifteen seconds to justify the next five minutes, and a paragraph of context spends that budget on something they already know. Put the number in the first sentence. Everything after it is now being read by someone who has decided the post is worth reading, which is a different and much more forgiving reader.

The fourth item is the one that separates a post people trust from a post people skim. What did not work is the part nobody else publishes, and it is the part that is most useful to a reader who is about to try the same thing. It is also the cheapest possible signal that you are reporting rather than selling.

One written out#

Here is the whole thing at the length it should be. The study is invented, and deliberately small; the shape is what to copy.

My LLM judge agreed with itself 91% of the time and with me 74%
---------------------------------------------------------------

I graded 200 support-bot answers three times: twice with the same judge
prompt at temperature 0, and once by hand. The judge agreed with its own
earlier verdict on 182 of 200 (91%). It agreed with me on 148 (74%),
which is Cohen's kappa of 0.42 -- moderate, and lower than I would have
guessed from watching it work.

[Figure: a 2x2 confusion matrix, my label against the judge's. The
 off-diagonal is lopsided: the judge passes 41 answers I failed, and
 fails 11 I passed.]

WHAT I DID.  200 answers sampled from a week of traffic, stratified so a
quarter were ones the bot had flagged as low confidence. One judge
prompt, asking for pass or fail and a reason, run twice with the same
seed and temperature 0. I graded all 200 myself first, without seeing the
judge's output, and I did not revise my labels afterwards. Code and the
anonymised answers: github.com/<me>/judge-agreement.

WHAT SURPRISED ME.  Self-consistency at 91% looked like a good sign and
was not informative. A judge that always says pass would be 100%
self-consistent. The number that mattered was the agreement with me, and
almost all the disagreement was in one direction: the judge is lenient
about answers that are fluent and wrong.

WHAT DID NOT WORK.  Asking the judge to be strict moved raw agreement
from 74% to 76% and kappa not at all -- it started failing answers I had
passed, at about the rate it stopped passing ones I had failed.

LIMITS.  One judge prompt, one model, one product, and one grader, who
is me, and I knew which system produced the answers. Kappa against a
single unblinded human is an upper bound on how good this judge is, not
a measurement of how good it is.

NEXT.  Two graders, blinded, on the same 200, so I can see whether 74%
is the judge's ceiling or mine.

Read the limits paragraph again, because it is doing more work than it looks. It does not say results may not generalise. It names four specific conditions, admits the grader was unblinded, and then draws the consequence out loud: this is an upper bound, not a measurement. A reader who knows the area now trusts the rest, and a reader who does not has been told exactly how much to conclude. That paragraph costs four sentences and buys everything else in the post.

Showing the code#

A link to a repository is not showing the code. The reader who would have been convinced by your code will not clone anything, so put the ten lines that contain the idea directly in the post — the metric, the loop that produced the number, the prompt — and link the repository for the person who wants the rest. Ten lines in the page get read; a repository gets a click from one reader in fifty.

What the repository has to earn is the second click. One command in the README that reproduces the headline number, the data or a generator for it, and the versions you used. A repository where the reader has to work out which of eleven scripts made the figure converts an interested person into someone who assumes the result would not reproduce.

Keep it honest#

Say what the result does not show: the small scale, the single dataset, the seeds you had. Readers trust writers who mark their own limits, and experts will notice if you do not.

Two habits carry most of this. Give every number the thing it was measured on and the variation you saw, because a number without either is a claim rather than an observation. And when you do not know why something happened, write that you do not know, rather than the plausible mechanism you thought of afterwards. The invented explanation is the single thing most likely to be the one an expert reader can tell is wrong, and it costs you the parts of the post that were right.