Question on the detail of a document

DBML Syntax
1

Any one following some thing like this (got this from Claude) when it comes to documenting a table

Grain: one row per issue. Epics, Stories, Tasks, Bugs, and Sub-tasks all live in this
same table — tell them apart using ISSUE_TYPE_ID.

Use for: looking up one issue’s status, owner, dates, estimates, and any single-value
custom fields.

Always filter: check ISSUE_TYPE_ID before adding numbers together across rows (e.g.,
summing Story Points across an Epic and its child Stories double-counts the same work).

Caveat: around 140 columns; most past the first 60 or so are custom fields added over
time and are mostly self-explanatory. Only the ones with notes above have a hidden
trap worth knowing about.

Note: not a history table — this only shows the current state of each issue, not what
it used to look like before.

2

Yes, you can use DBML Note syntax:

Table issues {
  id int [pk]
  issue_type_id int [note: 'Epic, Story, Task, Bug or Sub-task']
  story_points int [note: 'Do not sum across an Epic and its children']

  Note: '''
  **Grain:** one row per issue. Epics, Stories, Tasks, Bugs and Sub-tasks all live here, tell them apart with `issue_type_id`.

  **Always filter:** check `issue_type_id` before summing across rows. Adding Story Points across an Epic and its child Stories double-counts the same work.

  **Not a history table:** current state of each issue only.
  '''
}

If you publish to dbdocs, there is also a built-in Markdown editor for table and field notes, so you can fix wording in place without rebuilding the project.