Contributors Guide


Hi8mm crash record artifact found in the Jerome Caja Project

Table of Contents

  1. Basics
  2. Sending a Github Issue
  3. Editing an Artifact Page
  4. Adding a new Artifact

Basics

Thank you for checking out the Contributors Guide! AVAA could not be sustained without a dedicated community of loveable av nerds like you.

This guide is designed as a simple step-by-step for contributing via GitHub or Prose. If what you read here doesn’t make a whole lot of sense, consider treating yourself to a crash course in git, GitHub, and the Markdown language (a little HTML helps too). It’s all very easy, we swear. Some resource recommendations are in our FAQ page.

Most pages will have links at the bottom that say “Edit in GitHub” or “Edit in Prose.”

You can embed video examples from anywhere, but it’d be great if you can send an upload request to add them to the AV Artifact Atlas Collection on Internet Archive.

Sending Github Issues

See a typo? An error? A complete and total fabrication? Send an Issue!

Have an idea for a new artifact (or how to expand on an existing one), but just don’t have the know-how to edit in GitHub? Send an Issue!

Have an artifact that you can’t identify and would like the opinion of the community? Send an Issue!

  • Click on link at the bottom of an artifact page
  • Click on “New Issue” in the top right
  • Fill out the form with the kind of change you would like to see made
  • For artifact identification help, begin your subject line with “Artifact” as in “Artifact: Weird lines and stuff”
  • For ideas you have on functionalities that could make AVAA better, begin your subject line with “Wishlist”

How to update an artifact page through the AVAA website

Edit in Github

  • Click on link at the bottom of an artifact page
  • Log in (if not already logged in)
  • Click on edit file button (pencil icon above text)
  • Preview results
  • Fill out the “Commit Changes” box at the bottom of the page and choose “create a new branch and start a pull request”

(Note: you can also just go straight to the artifacts directory.)

Edit in Prose

  • Click on link at the bottom of an artifact page
  • Log into Prose using Github credentials (if not already logged in)
  • Edit page and preview results
  • Click the Save button (last button on right navigational bar) and submit your change request

Add Images

Images are linked. As the future-proofing types, we recommend images are first uploaded into the images directory of the repository. (Note that you will not see the images in GitHub, only on the website.)

  • Upload image to images directory
  • Insert image under the “Example(s)” header in the style below, replacing the file name with the one you just uploaded.
  • Add a description. The sub tag in the example below creates a comment under the image where you can describe the source.

<img src="/images/TBCerror_compare_02.jpg"> <sub>TBC Error</sub>

Add Media

Submit a Media Upload Request

The large sizes of sound and video files means that these examples should be embedded from other sharing platforms. In the interest of keeping these items together, we ask that contributors send the video and audio they’d like to add to the issues tracker. An administrator at Bay Area Video Coalition will then add the media to the organization’s Internet Archive or Soundcloud account.

Once uploaded, the admin will send you a link and you can continue with the steps below.

Note that from Internet Archive and Soundcloud these files can be easily downloaded by anyone. If you would prefer to embed on your own from a more secure sharing platform, that is fine too.

Add Video

  • Link to your video to the issues tracker. Administrators will upload the file to Internet Archive and send you a link.
  • Copy the embed code from Internet Archive.
  • Paste into the artifact’s page under the “Example(s)” header.
  • Change the default width and height of the video in the embed code to width="560" height="315"
  • Add a description. The sub tag in the example below creates a comment under the image where you can describe the source.

The sample syntax below embeds video in both Prose and GitHub. Replace only the URLs and the description.

<iframe src="https://archive.org/embed/AVAAAvatlasBeardingAccess" width="560" height="315" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen></iframe> <sub>Bearding as seen in 1/2 open-reel AV recording. Source: [Nancy Karp +Dancers](http://www.nancykarp.org/)</sub>

Add Sound

  • Link to your audio to the issues tracker. Administrators will upload the file to Soundcloud and send you a link.
  • Copy the embed code from Soundcloud
  • Paste into the artifact’s page under the “Example(s)” header.
  • Add a description. The sub tag in the example below creates a comment under the image where you can describe the source.

The sample syntax below embeds audio in both Prose and GitHub.

<iframe width="100%" height="450" scrolling="no" frameborder="no" src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/96915790&amp;auto_play=false&amp;hide_related=false&amp;show_comments=true&amp;show_user=true&amp;show_reposts=false&amp;visual=true"></iframe> <sub>Dropout heard in 1/4" open reel audio</sub>

Tips on writing in Markdown

  • Note that {{ site.baseurl }} must be appended to the beginning of links and images. Images will not show up in the Github markdown page but will work on the website.
  • If you want to make a line break (or new line), you have to add two spaces at the end of the previous line.

For more advice, see this Github Guide to Mastering Markdown.

Adding a new Artifact

To add an artifact that is not listed, you must make a new page. New pages should be made in the _artifacts directory. The file should be named the same as the title of the artifact and end in .md (because it will be a Markdown file). If the artifact is more than one word, use underscores to represent spaces in the title. All artifacts require some specially-formatted text called YAML at the top of the file. Here is an example from the Bearding Artifact (found in _artifacts/muffled_sound.md):

---
layout: post
title: Muffled Sound
categories: audio analog
namevar: [Azimuth Error]
tags: [Audio, Analog, Azimuth, Error, Frequency Loss, Playback Adjustment, Media Failure, Media Damage, Oxide Out]
---

Categories should be limited to the following: analog, audio, digital, film, and video. Categories should be written in lowercase and, if using multiple categories, separated by only a space (no commas).

The “namevar” category shows up in search results as “also known as”. This is so people can still search for something and find the right artifact. If your new artifact is known by other names, enter them here, separated by commas, in brackets.

Tags are free text and help other users search and find artifacts. Tags should be wrapped in brackets and separated by commas.

Below this, add a top-level brief description, a ## Definition section, and a ## Can it be fixed? section. Add examples, if available, in an ## Example(s) section. See above for more information about editing artifacts, examples, and writing in Markdown.