Editorial Guide

This document describes the responsibilities for the person or people assigned to the editor role for an open source story, as outlined in the editing section of the new-story issue template.

Would you like to be an editor for Open Source Stories? Let us know by sending us an email at contribute@opensourcestories.org!

Editing process

As the editor for a new story, you will be given access to a Google Drive folder containing the following resources:

  • a transcript in the desired output template (Google Doc)
  • the audio recording (.mp3)
  • subtitle files (.srt and .vtt)

Most of your work will be completed in the transcript document, and tracked in the assigned GitHub issue for transparency.

Editing a story can be broken down into the following steps:

  1. edit transcript for readability
  2. break into paragraphs
  3. fine-tune title
  4. add logical headings
  5. add a summary
  6. add relevant links (optional)
  7. suggest tags (see opensourcestories.org/tags for existing tags)
  8. write social media copy (optional)

Edit transcript for readability

The transcript is what will be posted on opensourcestories.org, but can be edited for clarity. This means that filler words (ums, ahs, like, etc…) may be removed if they impact the readability of the story. A suggested process is:

  1. read through the transcript and correct misspellings, grammatical errors, or mistranscriptions
  2. add punctuation where needed
  3. tighten up language and clarify ambiguities

Break into paragraphs

While the transcript will already have some paragraphs based on speaker and timing, if there are additional breaks that you find would be helpful, please add them.

Fine-tune title

The transcript will have a draft title, but please feel free to fine-tune it if you have a more appropriate one. Puns are greatly appreciated and highly encouraged. Embrace your creativity!

Add logical headings

Even short stories can use some structure! Please add 3-5 headings (H2) in the story as the conversation progresses. You can look at prior stories to get a sense for how we have broken them up in the past.

Add a summary / description

The summary does not appear on the story page, but does appear in the story listing, and it populates the summary for the corresponding podcast episode. Add a 1-3 sentence summary of the conversation, highlighting salient points.

If there are references to people, technologies, or events that you think could benefit from a reference, please add them as links in the transcript.

Suggest tags (optional)

Tags help people find other interesting stories! Add the tags you think would be most helpful for others.

See opensourcestories.org/tags for existing tags

Write social media copy (optional)

Social media, that fickle medium. If you are so inclined, please write a version (or two, or three) of text that we can use to promote the story on Mastodon, Twitter, LinkedIn, etc…

  • Twitter limited to 280 chars unless subscriber to Twitter Blue
  • LinkedIn allows up to 5075 chars for message body
  • Mastodon defaults to 500 char limit in post; may vary by server

Tracking progress

Please keep track of your progress in editing in the issue for the story. We would say that not update is too small, but maybe ones like “opened a file 🎉” are. In general letting us know where you’re flowing, where you get stuck, and how we can help benefits everyone.

Once you have finished your tasks, assign the issue to the person who is named as the publisher for the story.

We are all human! If there are delays of more than ~4 days, or you can no longer be the editor, just let us know on the issue.