File and Folder Formatting Guide

Since Obsidian works with standard Markdown files, there is some amount of file management that is necessary to manually maintain. This wiki article is intended to describe the format of files and folders that we want to maintain in this knowledgebase.

Folder Structure

We aim to keep each file of a manageable size, this informs the way we split files and folders out. Taking the content folder in the root of the repository, the split should look something like this.

content
├── major-task-1
│   ├── track-1 (Track 1 of major task 1 has steps 1a, 1b, and 1c).
│   │   ├── media
│   │   │   ├── stage-1a-img1.jpg
│   │   │   ├── stage-1a-img2.jpg
│   │   │   └── stage-1b-img1.png
│   │   ├── 1a.md
│   │   ├── 1b.md
│   │   └── 1c.md
│   ├── track-2 (Track 2 of major task 1 has steps 2.1 and 2.2).
│   │   ├── media
│   │   │   └── step-2-1-screenshot.png
│   │   ├── step-2-1.md
│   │   └── step-2-2.md
│   └── track-3 (Track 3 of major task 1 has only one step, step 3).
│       ├── media
│       └── 3.md
└── major-task-2
    └── ...

Here is the dissection of how this works:

• The first layer of folder structure is labeled "major task" here. A major task is any set of instructions that does not belong with others. For example, FRC A/V setup and FTC A/V setup could be two major tasks.
• The second layer of folder structure is labeled as "tracks" here. A track is any set of instructions within the major task that can be executed independently of another. Tracks may have dependencies on one another, but their steps can be carried out without significant reliance on steps in another track. For example, within an A/V setup context, setting up cameras and setting up the projection screen are two tracks; while the screen is useless without the cameras, the steps can each be carried out independently of one another, as the screen will not fail to have one of its legs because the cameras have not been set up yet.
• Inside each track are the individual stage files. The stages are (either directly or indirectly) dependent on one another, and must be carried out in order one at a time. For example, within an A/V setup context, two stages would be assembling the projection screen and turning on the projector. There is no point in turning the projector on first; the screen must be in place before any projector work can be done.
• Within each stage there are a number of steps, whose level of detail and wording are discussed in the Style Guide article.

For a unified look and feel, the first and second layer of folder structures must be replicated as shown here, though what each is named is up to the author. Feel free to call them "phases" or another preferred term instead of tracks, if desired. Additionally, the numbering scheme can be tailored as desired, though we ask that you keep it consistent within a given major task (i.e., don't do what is shown above, where the steps go from 1a, 1b, and 1c to 2.1 and 2.2).

File Structure

Each document is in the Markdown format, specifically a flavor of Markdown called Obsidian Flavored Markdown. The editing tool (Obsidian) provides a graphical interface that is ideal for creating these Markdown files. Contributors with technical expertise should still use Obsidian to take advantage of Obsidian-specific features, like callouts.

Content in a Markdown file should be placed in a folder as outlined in the above section. Each file represents one step of one track of one major task. Within the file, this structure should be followed:

1. Article title. This is placed at the top by Obsidian, so this can't be missed. The title should contain the stage or step number as well as a brief description of what the article contains instructions for.
2. (If applicable/desired) File properties.
   File properties allow a signal to be sent to the site generation tools. See this article for how to set a property. While many properties are recognized, the following two are most useful:
   The draft property, when set to the value true, suppresses the article from being included in the site generation. We suggest this be used if an article is unfinished or needs input or review from anyone else. See below for how this looks within Obsidian.
   
   The title property allows a custom page title to be defined. Without this set, the file name will be used. The file name is generally acceptable, but sometimes (like for an index page), it is better to set a custom one. See below for how this looks within Obsidian.
   
3. A repeating pattern for each distinct step, consisting of:

   • (If applicable/desired) Callout notice. The callout notice should be used sparingly for critical notes. Use them only to convey very important information (e.g., if equipment damage or injury is likely if the particular callout is not followed) or for troubleshooting/operational notes. The latter case is to help break this content visually from the setup documentation so that it can be quickly recalled if necessary. See this article for how to create a callout. It can also be added through the right-click menu.
     

   • Step number. This should remain constant throughout the document (i.e., no duplicated numbers), and be a maximum of two levels deep (i.e., step 2 may have a sub-step 2a, but 2a should not have a step 2.a.1.)

   • Setup instruction. The 'meat and potatoes', describing a particular action or item. See the Style Guide for information on how to write these.

   • (If applicable/desired) Picture(s) illustrating the action. No more than two should be supplied per individual instruction.