add introductory paragraphs to common data types

9 files changed, 69 insertions, 9 deletions

diff --git a/documents/album.md b/documents/album.md
index 7b79f7c..4f4c7db 100644
--- a/documents/album.md
+++ b/documents/album.md
@@ -1,10 +1,14 @@
 # Album Format
 
+> Albums form the bulk of content on a music wiki! They're the kernel of data everything else is structured around: related albums are collated in groups, albums contain tracks, albums credit artists, albums include art tags and their tracks are featured in flashes, and so on. The process of adding totally new data to a music wiki almost always starts from albums.
+> 
+> Albums contain lots of objective data about a release and its tracks, such as release date, personnel/artist credits, related groups, listening URLs, and so on. Albums also cover the presentation of a release and its tracks, with styling info such as theming color, wallpaper and banner, and miscellaneous configuration like disabling track numbers altogether. And albums can contain lots of surrounding goodies, such as sheet music, bonus files, and artist commentary!
+
 Album documents are stored each in its own file, alongside all the tracks associated with that album, at `album/<directory>.md`. Albums are represented by the first document in an album file, with all the rest being track (or track section) documents.
 
 A typical album file will, in its entirety, look something like this:
 
-```yaml
+```
 # /path/to/data...   /album/homestuck-vol-7.yaml
 Album: 'Homestuck Vol. 7: At the Price of Oblivion'
 Directory: homestuck-vol-7
@@ -29,7 +33,7 @@ Artist: Michael Guy Bowman
 
 ## Album documents
 
-Referenced as `album:directory`; extra links: `[[album-commentary:directory]]`, `[[album-gallery:directory]]`.
+Referenced as `album:directory` or by name; extra links: `[[album-commentary:directory]]`, `[[album-gallery:directory]]`.
 
 ### Essential info fields
 
@@ -87,7 +91,7 @@ Referenced as `album:directory`; extra links: `[[album-commentary:directory]]`,
 
 ## Track section documents
 
-* `Group`: track section name
+* `Section`: track section name
 * `Color`: color-codes track sections if specified
 * `Date Originally Released`: default applied to tracks in this section
 
diff --git a/documents/art-tag.md b/documents/art-tag.md
index fbfaf7e..cb932f8 100644
--- a/documents/art-tag.md
+++ b/documents/art-tag.md
@@ -1,10 +1,12 @@
 # Art Tag Format
 
+> Art tags are added to albums' and tracks' art to make locating artworks with similar features easy. They're also used to apply sensitive content warnings to certain works, which makes covers show a notice and take a click before the artwork is revealed. Art tags are a very simple system, so they can be used to tag just about anything — on HSMusic we tag mostly specific characters, animal species, and settings. If you're adding a new album with lots of art, it's a good idea to [learn about tagging artwork for HSMusic.](../guidelines/art-tags.md)
+
 Art tag documents are stored all in one file, `tags.yaml`, one document (entry) per tag.
 
 ## Art tag documents
 
-Referenced as `tag:directory`.
+Referenced as `tag:directory` or by name.
 
 * `Tag`: art tag name
 * `Directory`: unique identifier among other art tags
diff --git a/documents/artist.md b/documents/artist.md
index 38fa1ad..f486799 100644
--- a/documents/artist.md
+++ b/documents/artist.md
@@ -1,5 +1,7 @@
 # Artist Format
 
+> Artists are the people responsible for all the music and artwork shared and storied through a music wiki! The actual data files only contain essential info about artists; when you visit an artist's music wiki page, all their crediting information is automatically filled in based on all the data in tracks and other data objects. No need to maintain a prolific composer's lengthy track list yourself!
+
 Artist documents are stored all in one file, `artists.yaml`, one document (entry) per artist.
 
 ## Artist documents
diff --git a/documents/flash.md b/documents/flash.md
index 96ac9a1..3015abd 100644
--- a/documents/flash.md
+++ b/documents/flash.md
@@ -1,12 +1,14 @@
 # Flash Format
 
+> Flashes make a handy little view for interactive or animated pieces in a larger work. Admittedly, they're definitely Homestuck-centric, so they're not super flexible for fitting into other sorts of wikis yet! Flashes feature tracks (which will automatically link to the flashes they're featured in) and can have contributor credits. They're sectioned by flash acts, which make for a dynamic (albeit currently hard-coded) sidebar and a very fancy gallery-style index.
+
 Flash documents are stored all in one file, `flashes.yaml`, one document (entry) per flash. They're grouped by flash act documents.
 
 The website section for flashes is called "Flashes & Games". Apart from this, these data objects are always called flashes.
 
 The flashes file will, in its entirety, look something like this:
 
-```yaml
+```
 Act: Act 1 - The Note Desolation Plays
 Anchor: a1
 Color: '#7799ff'
diff --git a/documents/group.md b/documents/group.md
index e65f9fe..39a3d62 100644
--- a/documents/group.md
+++ b/documents/group.md
@@ -1,10 +1,12 @@
 # Group Format
 
+> Groups are all about organizing related albums into a distinct chronology and giving it context! For most visitors, they're the starting point for exploring and navigating a wiki; they give the wiki its top-level structure, and are also the main data source used in the homepage's layout. Groups are a very general feature, and can be made for a wide variety of uses! Groups themselves are categorized, so you can use groups for multiple purposes on a single wiki — the Homestuck Music Wiki uses groups for music teams, bands, and solo musicians, "fanventures" and game projects with multiple releases, as well as an essential scope identifying how closely tied any album is to Homestuck itself. If you're contributing one or more new albums, [learn more about grouping albums for HSMusic.](../guidelines/groups.md)
+
 Group documents are stored all in one file, `groups.yaml`, one document (entry) per group. They're further categorized by group category documents.
 
 The groups file will, in its entirety, look something like this:
 
-```yaml
+```
 Category: HSMusic
 Color: '#0088ff'
 ---
diff --git a/documents/static-page.md b/documents/static-page.md
index e47a0c5..54c00b4 100644
--- a/documents/static-page.md
+++ b/documents/static-page.md
@@ -1,10 +1,12 @@
 # Static Page Format
 
-Static page documents are stored each in its own file, at `static/<directory>.md`.
+> Static pages are the least networked and most "meta" part of a music wiki! Static pages represent top-level locations like About & Feedback, the invite to the HSMusic community Discord server, a years-spanning changelog, and more. They can be used for just about anything, but are also totally outside the scope of almost any data additions (save for keeping track of new content in the changelog, for example).
+
+Static page documents are stored each in its own file, at `static/<directory>.yaml`.
 
 ## Static page documents
 
-Linked as `[[static:directory]]`.
+Referenced as `static:directory`.
 
 * `Name`: static page name
 * `Short Name`: for use in e.g. homepage navigation bar
diff --git a/documents/track.md b/documents/track.md
index 5ba85ff..ac0174d 100644
--- a/documents/track.md
+++ b/documents/track.md
@@ -1,7 +1,47 @@
 # Track Format
 
+> Tracks are by far the most populous type of content on a music wiki. While albums have the most connections to other kinds of data, tracks themselves are the most "atomic" unit. Besides basic per-track information, HSMusic's strength lies in defining tracks in relation to each other: motif-referenced tracks, audio samples, re-releases, all tie tracks from different releases together in a wiki-wide net. And tracks automatically show up on artist's credit pages and in a selection of listings, all without ever duplicating anything in the actual data files — making wiki maintenance hassle-free and fitting new music into the wiki as a whole easy and rewarding!
+
 Track documents are stored in album files; after the album header document, use `Track: (Track Name)` to start a track document.
 
+Tracks only have a few key fields, with lots of additional fields filling in further details, bonus files, and relationships with artists and other tracks. So, some tracks are as detailed as this...
+
+```
+Track: Sburban Jungle (Brief Mix)
+Artists:
+- Michael Guy Bowman
+Duration: '1:36'
+URLs:
+- https://youtu.be/DKmXadfEnog
+Cover Art File Extension: jpg
+Referenced Tracks:
+- track:sburban-jungle
+Sampled Tracks:
+- track:sburban-jungle
+Sheet Music Files:
+- Title: Sheet music by Gamehunter
+  Files:
+  - 'Sburban Jungle (Brief Mix) - Gamehunter.pdf'
+MIDI Project Files:
+- Title: MIDI by Unknown
+  Files:
+  - 'Sburban Jungle (Brief Mix) - Unknown.mid'
+Commentary: |-
+    <i>Michael Guy Bowman:</i>
+    At this point I was just giddy about the release of "Sburban Jungle", although the version that appears here is deliberately truncated. The full version later released on [[album:homestuck-vol-4|Volume 4]] was already fully written at this point, although we figured that it would be best to give only a taste and otherwise save it for later.
+```
+
+...while others only handle the essentials!
+
+```
+Track: Once Upon a Time
+Duration: '1:28'
+URLs:
+- https://tobyfox.bandcamp.com/track/once-upon-a-time-2
+- https://www.youtube.com/watch?v=3BR7-AzE2dQ
+- https://open.spotify.com/track/4XX5uZb9PvTKh8Nm2KSJfk
+```
+
 > Certain fields inherit from the album the track is part of. **Save time by using the corresponding album field, if most of the tracks in an album share the same value** (differing from wiki default):
 >
 > * track's `Artists` inherits from album's `Artists`
@@ -12,7 +52,7 @@ Track documents are stored in album files; after the album header document, use
 
 ## Track objects
 
-Referenced as `track:directory`.
+Referenced as `track:directory` or by name.
 
 ### Essential info fields
 
diff --git a/guidelines/art-tags.md b/guidelines/art-tags.md
new file mode 100644
index 0000000..653258f
--- /dev/null
+++ b/guidelines/art-tags.md
@@ -0,0 +1,3 @@
+# Tagging artwork for HSMusic
+
+TODO.
diff --git a/guidelines/groups.md b/guidelines/groups.md
new file mode 100644
index 0000000..ccdcf9e
--- /dev/null
+++ b/guidelines/groups.md
@@ -0,0 +1,3 @@
+### Grouping albums for HSMusic
+
+TODO.
\ No newline at end of file