Contributors Guide


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.

The AVAA homepage can be accessed in one of two ways:

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

Send 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
  • File 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

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.

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="/avaa/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>