S1-Team Notebook

#all #documentation #standard

1 Purpose

The purpose of this document is to standardize practices for using and publishing to the Team Notebook.

2 Scope

All team members.

3 General Requirements

3.1 No spaces in file names (titles)

Authors shall use underscores (_) in place of spaces for all file names.

As files names are synonomus with the document title, this means that all titles must have underscores in place of spaces.

3.2 This is an Obsidian notebook

To maintain consistent inter-document links and style, all members shall author documents through the Obsidian program.

After cloning this repository to your local machine, open the folder as an Obsidian Vault.

3.3 Write dates in ISO-8601 format

All team members shall write dates in accordance with the ISO-8601 date format: Year-Month-Day (YYYY-MM-DD).

3.4 Require only free software

Grayson Robotics shall ensure that the team members can edit and read the Team Notebook with free software.

3.5 All file names shall be compatible with common OSs

Authors shall use file names that are compatible with Linux, Mac, and Windows file systems.

3.6 All document titles shall be unique

Authors shall chose titles that are unique from all other documents of the same type.

3.7 Everyone has to use it

All team members shall demonstrate the ability to read and update the Team Notebook.

4 Document Types

4.1 Memos

Memos are temporary notes, initial draft of Numbered Documents, or "todo" suggestions.

See: S6-Writing_Memos

4.2 Numbered Documents

4.2.1 Selecting document numbers

  1. Authors shall number documents sequentially, in the order they’re created.
  2. Authors shall select numbers that are unique from all other documents of the same type.
  3. Document numbers start at zero (0).
  4. Document numbers are integers.

4.2.2 Numbered document titles

Numbered documents all start with:

4.2.3 Using memos as drafts

When writing an initial draft as a memo authors shall omit the number, keeping the letter code and dash.

[!Example] The initial draft of this document would be titled "S-Team Notebook" prior to receiving the number "1".

4.2.4 Standards

Standards are for internal rules, guides, and process decriptions.

Letter code: S

See: Writing Standards

4.2.5 Projects

Projects are for project specific "todo" items and notes.

Projects use the start date instead of an index. The start date shall contain only the digits without separators.

Letter code: P

See: Writing Project Documents

4.2.6 Corrective Action Reports (CAR)

Letter code: C

See: Writing Corrective Action Reports

4.2.7 Quotes

Letter code: Q

Quotes are for externally produced reference material.

See: Writing Quotes

4.3 Wiki

This notebook includes a Wiki for informational documents with structures that are defined by Standards.

See: Notebook Wiki.

5 Technical usage

5.1 Use Pull Requests to make updates

  1. Team members shall follow the Pull Request Process to make edits to this repository.
  2. The IT dept. shall maintain S9-Pull_Request_Process.

5.2 Use the correct file format

Team members shall author all documents in Obsidian Markdown with the exception of links.

5.3 Rules for linking documents

Authors shall use GitHub compatible Markdown links (e.g. [display text](file path or URL)) rather than wiki style links (e.g. [[file path or URL|display text]]).

This is for the sake of navigating files in the Codeberg web interface which, at least for now, doesn't properly support Obsidian style links.

Authors shall ensure that each link is relative to the file it is in.

Given a directory structure:

notebook/
	README.md
	sub-folder/
		File_A.md
		File_B.md

To link to: README.md from: File A.md the link would be: [From File_A to README](../README.md). Note that ../ is a standard way to refer to the parent directory of the current file.

To link to: File_A.md from: README.md the link would be: [From README to File_A](sub-folder/File_A.md).

To link to: File_B.md from: File_A.md the link would be: [From File_A to File_B](File_B.md).

5.4.3 URL encoding

Authors shall ensure that links are valid URLs, which cannot contain spaces. Where a file name contains spaces, replace the space in the link with: %20 inside the link.

As all file names use underscores in place of spaces, this should only come up when linking to a heading or external website.

5.4.4 Obsidian app configuration

Team members shall ensure that their .obsidian/app.json file has at least these three properties set as shown:

{
  "alwaysUpdateLinks": true,
  "newLinkFormat": "relative",
  "useMarkdownLinks": true
}

6 Images and other attachments

Authors shall put images or other attachments in a sub-directory with the same title as the document using the image. The title does not incluce the document number or file extention.

[!EXAMPLE] For this document (S1-Team_Notebook.md) the folder name would be: "Team_Notebook"

7 Tags

Authors shall use whatever tags you think will aid future users in finding the document. Prefer already existing tags to new tags where the tag you would add is similar to an existing one.

7.1 Add the "all" tag where appropriate

Authors shall add the tag: "all" to documents intended for all team members and departments.

7.2 Tag with the relevant Department

Authors shall tag documents with a tag with the same name as the departments it they wrote it for.

7.3 Add tags first in the document

Authors shall add tags to the top of the document after the title.

7.4 Add tags horizontally

Authors shall add tags horizontally (separated by space) rather than vertically (separated by new line).

8 Checking a PR for merge approval

PR authors shall ensure all links in files they have modified or added are relative.

8.2 Check document numbers

PR authors shall ensure all document numers are incremented correctly.

8.3 Use a merge commit

PR authors or reviewers shall create a Merge Commit when merging a PR.

9 Maintain guides for using the Team Notebook

The IT dept. shall maintain guides for using the tools necessary to interact with the Team Notebook on Codeberg via SSH, Git, Jujutsu, & the Codeberg web interface.

Authors shall begin each guide with a Purpose section (following the tags) that describes what the author intends to teach the reader.

9.1 Team Notebook guide index