Contributing and Errata

Back matter  ·  ~8 minutes  ·  How to report an error or propose an addition

This book is open, which means it is also unfinished in the ordinary sense that all textbooks are unfinished — except that here you can do something about it. Anatomy and physiology is a settled science at this level; pedagogy never is. Corrections, clarifications, better explanations, and new clinical and exercise material are all welcome.

Reporting an error

A useful report takes about two minutes to write and saves an hour of investigation. Include five things.

  1. The file and the section. src/ch16-heart.md, §18.4 — not "the heart chapter."
  2. The claim as written. Quote the sentence. Line numbers drift; quoted text does not.
  3. What is wrong with it. Factual error, internal inconsistency with another chapter, a number that contradicts one given earlier, a broken causal step, an ambiguous figure, or a Case File resolution that requires material the reader has not been given.
  4. The correction you propose, phrased as the replacement sentence where you can manage it.
  5. A source, for anything factual. A current physiology or clinical reference text, a professional society guideline, or a primary paper. "I was taught differently" is a real signal and worth sending, but it is a question rather than a correction.
FILE      src/ch19-respiratory.md
SECTION   §22.7, third paragraph
CLAIM     "A right shift of the oxyhemoglobin curve increases affinity."
PROBLEM   Reversed. A right shift DECREASES affinity and promotes unloading.
FIX       "A right shift decreases hemoglobin's affinity for oxygen, so more
           is released at any given tissue PO2."
SOURCE    [reference text, edition, page]

The highest-value reports, in order: a resolution that cannot be reached from prior chapters; a number that contradicts a number given earlier for the same patient; a mechanism with a missing or reversed step; a figure whose Described paragraph does not carry the same information as the diagram; and a Key Term that is bolded in the text but missing from the list. All five are structural failures rather than opinions, and all five are fixed immediately.

Reports we cannot act on: requests to add images (see the Instructor Companion overview for why there are none), requests for clinical or diagnostic guidance, and requests to soften the clinical material. Disease is how this book explains normal function, and that is not negotiable.

The editorial standard

Four rules govern every page, and a contribution that violates one will be sent back regardless of how good it is otherwise.

This book teaches normal structure and function. That is the subject. Everything else serves it.

Pathology serves that goal, never the reverse. A disease earns its place only if it reveals a mechanism. The test is simple: strike the pathology and ask whether the reader's understanding of the normal case is weakened. If not, the sidebar is trivia, however interesting. "Rickets is a vitamin D deficiency" is trivia. "Rickets shows that the growth plate mineralizes cartilage, and that unmineralized cartilage is soft enough to bow under body weight" is a mechanism.

Nothing here is clinical advice. This is an educational text, not a diagnostic or treatment reference. Drug names appear only where a drug is an experimental interruption of a specific step — beta blockade, loop diuretics, ACE inhibition. Doses do not appear. Management algorithms do not appear. Where a clinical decision is mentioned, it is mentioned to explain physiology.

All patients are fictional. Every person in this book — the Osei–Barrett family and every one-chapter case — is a composite constructed for teaching. Contributions must be too. Never submit material derived from an identifiable person, and never submit anything that could be reconstructed into a real case. Numbers should be physiologically consistent and clinically plausible; they should not come from a chart.

Style requirements

Read AUTHORING-GUIDE.md in the repository root before writing anything longer than a sentence. It is not advisory. It specifies the exact heading structure the validator enforces, the required HTML patterns for callouts and figures, the six sidebar types and what each must do, the three recurring threads, and the voice.

The points contributors most often miss:

  • Every figure needs all three parts — the diagram, a caption block, and a described paragraph that renders the same information in prose. The described paragraph is required, is graded, and is not optional for "obvious" diagrams. A screen-reader user and a reader holding a photocopy must get the same content.
  • Numbers carry units and reference ranges. US conventional first, SI in parentheses.
  • Mechanisms run both directions. Give the causal chain, then ask the reader to predict from it. A passage that only describes is not finished.
  • Cross-reference generously, in §N.M form and as Markdown links, and only to files that exist.
  • No images, no external links, no LaTeX. ASCII figures and Markdown tables.

Proposing a new clinical vignette or Exercise & Sport sidebar

These are the most-wanted contributions, and instructors are the best source of them because you have watched real students fail to understand real things.

A Clinical Connection proposal should include: the chapter and section it belongs to; the mechanism it is meant to reveal, stated in one sentence; the presentation with specific findings and numbers; and the explanation, which must use only material available at that point in the book. Three hundred words is a typical finished sidebar. If the explanation requires a chapter that comes later, say so — it may belong in the later chapter instead.

An Exercise & Sport proposal follows the same form with one addition: it must be written at the same technical level as the clinical material. Kinesiology, athletic training, and exercise science students are roughly half the audience for this course, and the standing complaint about every other textbook is that they are served a paragraph and a fiber-type table. Physiology under maximal load is a rigorous subject; write it that way.

Misconceptions are equally welcome. The Common Misconceptions page is built from teaching experience, and yours is as good as anyone's. Send four things: the misconception in the words your students actually use, why you think it appeals, what is actually true, and — the part that matters most and is hardest to invent — the specific demonstration, question, or analogy that you have watched break it. A misconception without a break is a complaint; a misconception with a break is a teaching tool.

Also wanted: exam items that discriminated well in your section, low-cost and no-cost lab alternatives that worked, and pacing changes that fixed a chronic problem in your format.

Licensing for contributors

By submitting a contribution you agree that it will be published under CC BY-SA 4.0, the same license as the rest of the book. In practical terms:

  • You keep authorship credit and are listed among contributors.
  • Anyone may reuse your contribution, including commercially, provided they attribute it and keep the license open.
  • You must have the right to license the material. Do not submit text, tables, figures, or question items copied from a commercial textbook, a publisher's test bank, or a non-commercially-licensed source. Reproducing a copyrighted item into an open book is not a favor; it is a legal problem that endangers the whole project. If you are adapting an idea, write it in your own words from your own understanding, which is in any case what produces the better version.
  • Material under CC BY, CC0, or public domain can be incorporated. Material under CC BY-NC or CC BY-ND cannot, because ShareAlike requires that the whole remain freely reusable.

Translations and adaptations

Translations are explicitly encouraged and do not require permission — CC BY-SA already grants it. Some practical guidance:

  • Translate the whole chapter, not fragments. A chapter is a designed unit: the opener sets up questions the resolution answers, and a partial translation strands the reader.
  • Localize the units and reference values, and say that you did. Lab reference intervals, measurement conventions, and clinical norms differ by country. Appendix B gives both US conventional and SI values as a starting point.
  • The case family may be localized. Names, setting, and health-system details can be adapted so the cases read as real to your students. Keep the physiology, the numbers, and the arc, because later chapters depend on them.
  • Mark it as a derivative. State the original title and author, note that changes were made, link the license, and license your translation CC BY-SA 4.0.

The same applies to adaptations that reorder, cut, or extend the book for a particular program. You do not need permission. You do need attribution and the same license.

Build and validation workflow

The book is an mdBook project with Python tooling. Before submitting anything, run the validator — a contribution that fails validation cannot be merged, and the validator will tell you exactly what is wrong.

make validate   # structure, required sections, HTML/fence balance, internal links
make index      # regenerate src/term-index.md from Key Terms and the glossary
make single     # compile everything into dist/human-anatomy-and-physiology.md
make build      # render the HTML book into ./book
make serve      # live-reload dev server at http://localhost:3000
make stats      # per-chapter word, figure, and callout counts
make all        # validate → index → single → build

python3 scripts/validate.py ch16-heart validates a single chapter, which is what you want while drafting. It checks that every required heading is present and correctly spelled, that figure, caption, and described counts are equal, that the div, details, and summary tags and the code fences all balance, that the minimum counts for callouts, sidebar types, and sections are met, and that every internal link resolves to a file that exists. Fix every ERROR before submitting. Warnings are advisory but usually worth heeding.

If you have edited scripts/chapters.tsv, run python3 scripts/build_summary.py to regenerate src/SUMMARY.md. Never edit SUMMARY.md by hand — it is generated, and a hand edit will be silently overwritten.

An open invitation to instructors

The parts of this book that are hardest to write are not the physiology. They are the things that only accumulate from teaching: the sentence that finally made excitation–contraction coupling land, the demonstration that killed the lactic acid myth in one class period, the exam item that separated the students who understood the countercurrent multiplier from the ones who had memorized a diagram, the lab substitution that worked when the budget was cut.

Most instructors have a folder of these. Most of those folders are lost when the instructor retires. If yours has anything in it, send it — that is the material this book most needs and the material no author can generate alone.

See also: the Instructor Companion, the license and disclaimer, and AUTHORING-GUIDE.md in the repository root.