Writing Conventions

Contents

Be clear, concise, and easy to comprehend

Writing documentation that is easy to read and understand is important for the success of your team.

We are committed to writing documentation that is clear, concise, and easy to comprehend. The following guidelines will help you create content that reinforces the excellence of our documentation.

New to Markdown?

See resources in #How-to guides

Writing Guidelines

Zettelkasten notes are atomic and autonomous.

In a nutshell,

  • Each note should contain one idea and one idea only. This makes it possible to link ideas with a laser focus.
  • Each note is self-contained and comprehensible on its own

Create one note per idea

Creating one note per idea applies to all documents, which I’ll talk more about below. Creating one note for each idea allows the most flexibility. You can then use that one note with other related notes in more ways than you realize. Imagine using index cards for your notes. You can take all of your notes and spread them out on the table. Then you can easily rearrange them, making connections between those notes. You can do the same thing in the digital format; however, your notes need to be atomic to accomplish this.

Give each note a unique ID

A unique Title will suffice. Read technical documentation if interested.

Write your notes in your own words

Doing so helps ensure you understand what you’re consuming. If you can’t write it in your own words, you likely don’t understand it.

Include context with your notes

Write your notes so that anyone, including your future-self, can understand them. This is especially helpful if you want to share a specific idea or even combine ideas into an article (like this one).

Connect your notes

Configure vscode-memo to create bi-directional links with ease in VSCode.

Use linking where appropriate to establish relationships.

[[<Title of your note aka. the Unique ID>]]

To understand how linking works, read [the neuron guide on Linking][linking].

Formatting

  • Use the correct format (i.e. headings, lists, tables, etc.)
  • Include a table of contents when two or more first-level and second-level headings are present. (“## and #" headings in markdown)
  • Format with heading styles (i.e. Heading 1, Heading 2)

At the start of every document, update the title in the document meta.

---
title: How to update this wiki
---

Footers

At the end of every document, add make a relationship with its parent document.

---

#[[<Parent Relationship>]]

The result is this below ⇓

#Croc

logo