B-Maker Explained

Editorial workflowComments vs notes

Why have comments if the project already has notes?

Because some thoughts are about the project, while others belong to a specific piece of text.

The attachment test

If the thought loses meaning when separated from this passage or version, make it a comment. If it remains useful independently, it is probably a note.

Comments preserve editorial context

“Check this number,” “the editor questioned this claim,” “keep this sentence because it pays off in Chapter 9,” or “rewrite this after the interview” make sense because they point to a specific place.

Notes hold broader thinking

Research ideas, possible themes, future chapters, references, questions about the whole book, and material that may move belong in a more independent space.

Why not write TODO directly into the manuscript?

Sometimes that is fine during an early draft. But inline TODO markers can accidentally reach export and become harder to distinguish from intentional text. Comments keep the task beside the prose rather than inside it.

Screenshot: comment vs noteLeft: a passage comment attached to one sentence and a general version comment. Right: a broader project note about research or a future chapter.assets/img/bmaker/bmaker-explained-comment-note-01.webp

Comments can also preserve why

Revision history tells you what changed. A comment can preserve why a strange sentence stayed, what still needs verification, or what a reviewer meant. That context is often more valuable than another copy of the text.

Why versions exist · Revision workflow