style guide

Note naming

• The general goal is to minimize the use of aliasing in links. In case where these guidelines suggest an unnatural or uncommon name that would require lots of aliasing, prefer the natural usage.
• When a page might be used to describe a platonic concept, prefer singular to plural.
  • Example: testable prediction rather than 'testable predictions'.
  • Reason: it's easier to pluralize a singular link than to singular-ize a plural link.
• Avoid capital letters except for explicitly proper nouns.
  • Example: reinforcement learning rather than 'Reinforcement Learning'.
  • Reason: this makes the term easier to link from a sentence.
• For verb phrases, prefer the simple present tense in its base form: the form you'd use with a subject of I/we/you/they, as opposed to he/she/it.
  • Example: carve the world at the joints rather than 'carves' (as in 'it carves') or the present continuous 'carving'.
  • Reason: this form is both the most basic and the most flexible, since we can often augment it with helper words ('will carve', 'does carve', 'did carve', etc.) to work in the necessary context.

Tags

• A tag groups related pages on some topic. Unlike folders, tags can overlap; a page can have multiple tags.
• Using a #tag on a page serves two purposes: it refers to the set of notes covered by the tag, and it adds the current note to that set. But sometimes we want only the former, i.e., we want to refer to a set from outside the set itself (for example, a note on my life goals may want to refer to the set of #math notes, but it should not itself be considered a math note). Here's a protocol for doing this:
  • Add a link to the page with the same name as the tag. (for example, a link to the math page). If this page doesn't already exist, it will be created.
  • On that page, add a query for notes that use the tag:

    ```query
    tag: #math
    ```

  • Thus, clicking on the link immediately shows us the set of tagged notes, without explicitly using the tag on the linking page.

Language

Prefer to write advice in the first person: e.g., "I should do X" or "I wish I'd done Y" rather than "You should do X".

• It's more honest. I really have no idea who you are or what you should do, but my report of my own thoughts about what I should do is authoritative. The reader can weigh my sentiments and draw their own conclusions.
• This pushes the reader to vocalize the "I" in her head, so from her point of view she's saying that she should follow the advice. I don't know if this makes a difference, but it sounds like the sort of thing one could write a bs psych paper on.

Markdown

• When writing LaTeX blocks, ensure that `
  $$` is never on its own line, but always on the same line as the text that precedes or follows it. That is, write ``` ```markdown Lorem ipsum dolor$$
  a = b
  $$sit amet... ``` instead of ```markdown Lorem ipsum dolor$$

sit amet...

This is ugly but unfortunately seems to be a requirement to keep Obsidian from splitting the LaTeX block into invalid pieces.
- Use the following pattern (from https://thesynack.com/posts/markdown-captions/) for image captions. Putting the HTML tags on separate lines allows the Markdown parser to process formatting within the caption text: ```
```markdown
![Alt text](path/to/image.png)

<figcaption>

Caption text.

</figcaption>