FOLIO Communication Spaces

The FOLIO Project has three primary communication channels and several secondary communication channels.  Read about the philosophy of the FOLIO communication channels for more background.

The primary communication tools are:

• Wiki
• Issues
• GitHub

Some general guidelines that apply to all tools:

• Decisions need to be recorded in an appropriate place. Sometimes that will be the Issue Tracker, sometimes it will be as a position paper on the wiki.  In all cases, decisions should be recorded on one of the primary communication tools.

• Use well-chosen words for topic titles and introductory sections. This will make it easier to later list and search topics.

• Make links in each topic, e.g. between an issue tracker item and relevant documentation. Our future selves will be thankful when we need to explore the reasons for a certain change. Note that it is also possible to copy links from the Slack archive into

• Try to search before starting a new topic. If there are duplicates, then link them.

• Do not expect immediate answers.

• Try to keep the discussion focused and as close to the source topic as possible. For example, if your feedback is about a certain GitHub commit, then use its comment-on-commit facility. Likewise with pull requests and issue.

Wiki - Documents

FOLIO uses this wiki (an installation of the Confluence software) to store documents with some permanence.  Each SIG has a space on the wiki, which can be found using the space directory.  

When to use the Wiki

• Posting agendas and minutes from meetings
• Publishing position papers describing proposed functionality

• Documentation for resources such as the Roadmap

• Marketing logos and branding documents

What to keep in mind when using the Wiki

The wiki uses the same account as issues.folio.org, but this is a different account from Discuss. You must set up your account on issues.folio.org first, but then you can log into the wiki with this account.

Issues - Bugs and Tasks

FOLIO uses issues.folio.org (an installation of the JIRA software) to track software development activity, request new features, report bugs in the software, and track tasks that have interrelated parts. The FOLIO Module/JIRA project-Team-PO-Dev Lead responsibility matrix lists the JIRA project for each module.

When to use Issues

• Recording software development tasks, assigning them to developers and tracking development progress
• Recording software bugs and commentary on those bugs
• Recording tasks that will need to be done at a later date and/or have dependencies on existing issues

What to keep in mind when using Issues

GitHub - Source Code

FOLIO uses Git repositories in github.com/folio-org to store the project's source code and to facilitate the integration of new code using GitHub's "Pull Request" functionality.

When to use GitHub

• Downloading and building the FOLIO project from the source code.
• Requesting new additions or changes to the code.

What to keep in mind when using GitHub

Secondary Communication Tools

There are a nearly infinite number of secondary communication channels; some of the most used ones are described here.  Any significant idea, issue, or discussion that occurs in a secondary channel should be recorded in a primary channel (Discuss, Wiki, Issues, or GitHub) for publication and vetting to the wider FOLIO community.

Mailing Lists

FOLIO uses mailing lists for internal communication in SIGs and committees. A directory of mailing lists is on the mailing list service homepage.  The homepage also includes a form for subscribing to a mailing list and (for existing subscribers) receiving an email message with a link to manage mailing list options.  (The "Account Login" button in the left sidebar of the homepage is for the mailing list administrator only.)

When to use Mailing Lists

• To read broadcast announcements, join the folio-announce email list. 
• Communication between active members of SIGs and committees (for instance: canceling or rescheduling meetings)

What to keep in mind when using Mailing Lists

• Mailing lists have limited visibility to the broader community.  Most communication happens via Slack. 

Slack

FOLIO uses a Slack team for real-time chat communication.  You can request an account in the FOLIO team using the automated web form.  (There is no review process for new account requests; the invitation is automatically sent to your email address.) Slack offers a getting started with Slack guide.

When to use Slack

• Quick introduction or follow-up to new ideas
• Fun banter between colleagues

What to keep in mind when using Slack

• Not everyone is on all of the time.  FOLIO participants work in many different time zones, and so you may not be reaching everyone with your conversation.
• Slack can quickly become overwhelming.  The daily commitment of FOLIO participants is a wide range, and significant points may be lost in a large scrollback buffer of text. Distill important points from Slack conversations into discussion posts (see Messages below).
• Slack is not a place to record decisions.  Slack's channel logs are the real-time thoughts of the participants (which can change over time).  They are difficult to search for a particular point and even harder to summarize.  Ideas and decisions should be recorded in Discuss, Wiki, or Issues, as appropriate.

Conference Calls

Most SIG online meetings and other FOLIO-related online meetings will be held using the Zoom meeting software (https://zoom.us/). See FOLIO Meetings with Zoom for the default password. The Open Library Foundation holds a license to Zoom and sets up meetings on behalf of the project. Information about times and joining SIG meetings is generally provided by the SIG on their wiki space. Requests for setting up special meetings should be sent to the OLE Project Manager at hlm7@cornell.edu.

Some teams meet in their Slack channel using Slack calls.

A visual overview is available at https://www.openlibraryenvironment.org/archives/date/2016/09 - Go to the “Participation Channels in FOLIO - How to Engage” session.

FOLIO Communication Channel Philosophy

Like similar open source projects of the same scale, we know we are going to need a variety of communication paths: channels where we are communicating in real-time -- like chat and conference calls and in-person meetings -- channels where we aren’t in real-time -- like mailing lists, blog posts and bug reports -- channels where we are physically located together in time and space, and channels where we are physically apart or separated by time.  We also know that there are and will be people who are focused full-time on the FOLIO project, those that have other responsibilities but need to track what is going on in the project, and those that are curious and just tracking the overall progress and ideas in the project.  We have also seen worldwide interest in FOLIO -- Europe, Middle East, North and South America.  And with that comes its own set of challenges across time and languages.  And finally, have a strong suspicion if not hope that the project will grow and evolve.  

With that in mind, we have set up primary communication tools and acknowledge that there is a wide variety of secondary communication tools that will make sense for people to use as needed.  The primary tools are the Wiki -- a document-centered tool, Issues -- an issue and task tracking system, and GitHub -- where the developers will keep track of code.  Almost everyone involved with the project will use the Wiki.  Issues will become more widely used as FOLIO apps are created and tested, although there is quite a bit of activity on Issues already for the project as a whole and the platform code development.  The primary tools were chosen because they address the challenges from the previous slide: they don’t depend on people working at the same time or in the same place, they have features that enable individuals to follow along on a topic when they have time, and they allow for multiple languages.  We also know there are a variety of secondary tools, including a project Slack team, Skype, WebEx conference calls, and face-to-face meetings.  These tools tend to be more immediate in nature, but that immediacy is also exclusionary because not everyone can participate.  There is a motto that The Apache Software Foundation uses to tackle this problem.  Apache is one of the oldest organizations supporting open source; it can trace its origins back to the development of some of the first web server code in the early 1990s.  Apache also has many of the same characteristics that FOLIO has: worldwide interest, full-time and part-time contributors, and growing and evolving projects.  Their motto is: “If it didn’t happen on a mailing list, it didn’t happen.”  Or, put another way, if a conversation or decision didn’t happen in a forum with some permanence that everyone has access to, then it doesn’t count.  We use a FOLIO variation on this motto: “If it didn’t happen on a primary communication tool -- Wiki, Issues, or GitHub -- it didn’t happen.”