Guide: Staff Introduction

Welcome to MousePaw Media! We’re really excited to have you aboard. This tutorial will help you get started. If you need additional help, contact your internship supervisor.

This tutorial will also get you started as a MousePaw Media employee. Read through it in order. Watch out for…

Important

These are things you should do now.

Warning

These are things you need to watch out for.

Employee Handbook

Our Employee Handbook outlines all the company policies, rules, and expectations for staff at MousePaw Media. You should be familiar with the latest version of these policies at all times.

We publish the latest version of the Employee Handbook at eco.mousepawmedia.com. Click Employee Handbook to view or download.

Important

Download the latest copy of the Employee Handbook from that link, and save it to your work computer for quick reference. Read it through now.

You will be emailed whenever a new version of the Employee Handbook is published.

Technical Requirements

You must have Linux, ideally an Ubuntu-based distro (version 20.04 or later), installed on your computer. See Ubuntu Setup: Installing for instructions on installing it. If you need help, contact Jason C. McDonald.

Although we work on Linux, you may access the Staff Network via Windows, macOS, iOS (Apple) mobile devices, Android mobile devices, or BSD-based operating systems if you need to.

Security

Your MousePaw Media account may grant you access to personal and private company information, advanced controls that can potentially harm our systems, and more. It is your responsibility to keep your MousePaw Media account secure!

Password Management

To save your MousePaw Media credentials, you should use a secure password manager. Never trust your web browser’s “save password” feature for this.

If you aren’t already using a secure password manager, install Bitwarden.

  1. Go to https://bitwarden.com and tap Get Started to create a free account.

  2. Use your personal email address, and create a secure master password. Your password should be long, unique, and never consist of pet names, relative names, or other personal information.

  3. Write down your master password and store it in a secure physical location. NEVER keep it on a digital device. Be advised, for security reasons, if you lose your Bitwarden master password, you will NEVER be able to recover either it or any information you stored in your Bitwarden account. A password reset on Bitwarden will erase everything in your account.

  4. Go to https://bitwarden.com/download/ and install the Bitwarden extension for your web browser and each of your devices. This will allow you to access your passwords and other secure data stored in Bitwarden from any device, so long as you know your master password.

Note

Set up Bitwarden now and store your MousePaw Media credentials. If you already use a different secure password manager, add your MousePaw Media credentials to that instead.

Multi-Factor Authentication

Passwords are a good first step in securing your account, but they’re not the whole story. If your password is compromised, Multi-Factor Authentication, or MFA, is the next line of defence. MFA requires that you use a separate physical device, like your smartphone, to verify that a login is indeed coming from you, and not just some random person who has your username and password.

To set up MFA, you will need to install an authenticator app. Unless you are already using another trustworthy authenticator app, please install one of the following:

  • To use your iOS or Android smartphone as your MFA device, install the Microsoft Authenticator app.

  • To use your Linux machine as your MFA device, install the Authenticator app from Flatpak.

Note

Set up an MFA authenticator app now.

In the sections that follow, you will be installing MFA for

  • Phabricator

  • Nextcloud

  • Mattermost

DO NOT skip those sections!

Security Tips

All the security tools in the world mean nothing without a good dose of common sense. Here are some very important things to keep in mind at all times.

  1. Never share your password with anyone. We won’t ask for it. Period.

  2. Store your passwords in your secure Password Manager.

  3. Don’t leave your work devices unlocked and unattended.

  4. Consider enabling full-disk encryption when you install Linux.

  5. Be careful clicking on unusual or disguised links in emails, even if the email looks like it’s from within the company or from a coworker. Verify URLs and SSL certificates before entering your password or other information.

  6. If you lose a device you’ve used to access your MousePaw Media account, or which you use for MFA, contact us immediately!

Recovering Access

If you lose access to your MousePaw Media account at any point, whether that’s a missing password or a lost or non-functioning MFA device, don’t panic! MousePaw Media administrators are able to reset passwords and MFA credentials.

To start the process, contact eco@mousepawmedia.com, or ping someone in the ~eco channel on Mattermost. We will arrange to work with you over video chat (for authentication purposes) to restore access to your account.

Staff Network

The Staff Network consists of seven major components:

  • SOGo [Email/Calendar] (mail.mousepawmedia.com)

  • Kimai (time.mousepawmedia.com)

  • Phabricator (phab.mousepawmedia.com)

  • Mattermost (chat.mousepawmedia.com)

  • Nextcloud (cloud.mousepawmedia.com)

  • Jenkins (ci.mousepawmedia.com)

  • Etherpad (pad.mousepawmedia.com)

  • LimeSurvey (papers.mousepawmedia.com)

We also use Jitsi Meet for regular communication.

Visit staff.mousepawmedia.com for our main staff portal, with links to everything else.

Email and Calendar

As with any job, email and calendar are essential. You were issued a company email address, which comes with a calendar and a contact book.

Warning

Be sure to check your company email every single day, and respond in a timely fashion!

You can check your email and calendar through the SOGo web client. This is useful if you don’t want to configure an external client, or need to check your email without access to your usual device.

SOGo Setup

SOGo is a modern webmail and calendar client with many useful features.

First, go to mail.mousepawmedia.com/sogo. Sign in using your full company email address and your password.

Important

Access your company email through the SOGo client.

Tap the gear in the upper-left to open Preferences.

You should set your time zone first. Under General -> General, set your Time Zone to the appropriate time zone for you. You may also want to select your preferred date and time formats.

Also consider checking Enable Desktop Notifications, so you will get notified of new emails when SOGo is open in your browser.

To set up your default signature, go to Mail and IMAP Accounts. Click the pencil next to your email address on that window, and click on your name under the Identity section.

Under Signature, add your signature. We recommend this template for your signature:

Your Name Here
Position, MousePaw Media

Visit Us Online: MousePawMedia.com
Twitter: @mousepawmedia

Press OK to save. Then, tap the green save icon in the upper-right corner to save your settings.

Warning

If you get a warning message about “Service temporarily unavailable”, you may ignore it. Your settings ARE saved. Furthermore, if you click anywhere to leave Preferences, and are warned of Unsaved Changes, you can select “Don’t Save”; pressing the save icon that one time did save your changes.

Important

Set up your settings and signature as documented above now.

SOGo Calendar

To navigate around SOGo, in the upper-right, click the Mail, Calendar, and Contacts icons.

The first time you click the Calendar, it will create a Personal Calendar for you. Any events you RSVP to will appear here. You can click the three dots to change the name and color of this calendar.

One of the particular benefits of SOGo calendar is how easy it makes scheduling. When you create an event, add the Attendees you want to meet with. SOGo will show you a chart of their free/busy times. (However, please be mindful of time zone differences as well.)

Importing Web Calendars

To make scheduling easier for everyone, you should subscribe to any external calendars (Web Calendars) you routinely use for scheduling. This may include a personal calendar, a work calendar, or a school calendar. To do this:

  1. Get the public CalDAV or WebDAV URL of the external calendar you want to add. If you’re concerned about privacy, at least enable a public link that shows free/busy status without event details. (If you need help with this, contact your mentor.)

  2. In SOGo Calendar, tap the + next to Web Calendars, enter the URL, and press OK. If you did everything right, the events from this calendar will appear in SOGo within a few moments.

  3. Tap the three dots next to the calendar, and select Properties. Set the name and color, and ensure Include in free-busy and Reload on login are checked. Press OK.

  4. Press the toggle switch to the left of the calendar name to hide it from your calendar view, if desired. Others will still see your free/busy status when scheduling an event where you’re listed as an Attendee.

Important

Import your web calendars now.

Setting Up Out of Office Hours

If there are times you are consistently unavailable, you may consider creating a separate Calendar on SOGo to block out these times.

To create this calendar:

  1. Click the + icon next to Calendars.

  2. Name the calendar “Out of Office”. Press OK.

  3. Click the three dots next to “Out of Office”, and click Properties.

  4. Select Include in free-busy. Unselect Show alarms and Show tasks. Press Save.

Now create events for your typical unavailabilities, such as days off and sleeping hours. On the event creation screen:

  1. Set Calendar to “Out of Office”.

  2. Unselect Send Appointment Notifications

  3. Set the day, time, and repetition. For example, if you take Sundays off,

you may create an “All day Event” that repeats “Weekly” on Sundays.

  1. Unselect Reminder.

  2. Press Save.

Important

Set up your Out of Office calendar now, with at least “Offline” hours for sleep.

Mail Settings

You can access a number of advanced settings for your email account by going directly to mail.mousepawmedia.com and logging in with your full email address and password.

Some things you can do from here include:

  • Viewing login history (from Mailbox -> General)

  • Adjust additional mailbox settings under Mailbox -> Settings.

  • Setting up temporary email aliases, which are useful when you need to provide an email address for something, but want to be able to delete it if it starts to receive spam.

  • Control spam settings, whitelist/blacklist email addresses.

  • Generate app passwords for IMAP/SMTP/CalDAV/CardDAV logins without exposing your company email address.

  • Check the intercepted spam in Quarantine, and take action on it (including

delivering to mailbox) by clicking Show item, scrolling down, and clicking Actions.

You can also jump right to SOGo from here via the Login to webmail button under Mailbox, or from the Apps menu at upper-right.

IMAP/SMTP Access

You can also connect your account to an external email client, such as Thunderbird or your mobile device.

You can find full configuration instructions by going to mail.mousepawmedia.com, going to Mailbox -> General, and scrolling down to the [Show configuration guides for email clients and smartphones] link. That will show customized instructions for your email account and our servers.

In short, here are the recommended server settings:

  • Username: (Your full company email address.)

  • Password: (Your company password.)

  • Incoming Mail: IMAP (recommended)

    • Server Name: mail.mousepawmedia.com

    • Port: 993

    • Connection security: SSL/TLS

    • Authentication method: Normal password

  • Outgoing Mail: SMTP

    • Server Name: mail.mousepawmedia.com

    • Port: 465 (recommended) or 587.

    • Connection security: SSL/TLS

    • Authentication method: Normal password

Important

Connect your company email to an email client, such as Thunderbird, Evolution, or your smartphone.

CalDAV Access

If you use an external calendar application, you can work directly with your MousePaw Media calendar via CalDAV.

The easiest way to get your CalDAV link is to go to SOGo <https://mail.mousepawmedia.com/sogo>, tap the Calendar icon in the upper-right corner, and click the three dots next to the calendar you want to access via CalDAV. Select Links to this Calendar.

Depending on whether your client uses CalDAV or WebDAV, select the appropriate link under Authenticated User Access. Your calendar application must support providing a username and password for this to work.

If you are using a calendar application that doesn’t support authentication on CalDAV or WebDAV, you can also use the Public Access link. You can control public access permissions by clicking the three dots next to your calendar and selecting Sharing…. You can provide either full or time/date-only read access for the three types of events.

Note

If you use Android, the easiest way to work with CalDAV is to use the DAVx5 application. It’s open source. You can download it for free from FDroid, but please consider buying it from the Google Play store to help support the creators.

Important

Set up your favorite calendar app with access to your calendar via CalDAV, so you can receive notifications of upcoming events.

Regular Email Tasks

  • Correspond with co-workers. Read and respond to messages in a timely fashion.

  • Schedule and RSVP for meetings.

  • Contact ECO to schedule time off, ask questions, and report concerns.

Kimai

Kimai is where we track time. You are responsible for reporting your time every day. Each day’s time sheets are locked automatically the next morning, but you should try to log your time before then.

Warning

If you forget to log your time, you will NOT be reminded. Contact eco@mousepawmedia.com if you forget, and report your time that way.

To log your time, go to https://time.mousepawmedia.com. Login using your company username and password.

You will be on the My times section by default.

We recommend creating separate entries for each major task you work on. This will make it easier for you to see how you use your time.

To add time, click the large Play button in the upper-right corner of the page. Fill out the following fields:

  • From: select the start date and time for your entry. You may estimate the start the time if you can’t remember it.

  • Duration: Enter the duration in H:MM format.

  • Project: Select Internal.

  • Activity: Select the project you were working on.

    • Most MousePaw Media projects have an entry here. If you don’t see the one you need, use General and contact your supervisor.

    • Use Research for general-purpose research and training.

    • Use General for meetings, internship assignments, and anything not covered by another category.

    • Use DevOps/IT for repository master, build system, and server work.

    • Use Operations for management, administrative, and standards board tasks.

    • Use Hiring for hiring-related tasks.

  • Description: When relevant, you must include appropriate Phabricator object codes, including Maniphest Tasks, Differential Revisions, Ponder Questions, wiki pages, and the like.

Warning

These notes are not a replacement for your Dev Journal entries.

Finally, click Save in the lower-left corner to store the hours.

Warning

Kimai’s date/time selector is a bit unintuitive. You must click the green Confirm button to keep the date/time you chose in the selector.

While you’re here, take a look at the Dashboard, Calendar and Reporting tabs. These give you detailed breakdowns of your hours, including what you worked on and when you worked.

If you need a tool to help you track your time, check out the Timecard application, created by Jason C. McDonald.

Regular Kimai Tasks

  • Log your hours every day you work.

  • Seriously, that’s it. Log your time!

Mattermost

We use Mattermost, an open source chat service, for team chat. All staff members are expected to be logged into Mattermost during work, and are strongly encouraged to stay signed in when convenient to facilitate collaboration and communication.

Mattermost can be accessed directly through the web browser from chat.mousepawmedia.com, but we strongly recommend installing the official client, which works on Linux, Windows, macOS, Android, and iOS. You can download and install the client from mattermost.com/download.

Important

Install the Mattermost client on your work computer, and if possible, on your mobile device.

Creating Your Account

Mattermost is the only service we use which is not tied to your MousePaw ID. Instead, you’ll need to create an account using the invite that was sent to your MousePaw Media email address. You must sign up using your company email address, or else you will be unable to access our chatrooms.

Important

Sign up using the invite that was emailed to your company email address.

Once you’ve signed in to Mattermost, either through the website or the client, you should immediately set up your user profile. Click your profile picture in the upper-left corner and click Account Settings. Add your Full Name, your Profile Picture, and anything else you want to add.

Important

Log into the MousePaw Media Mattermost and set up your user profile with your Full Name and Profile Picture.

At this time, you may want to take a minute and look through the other Account Settings, especially…

  • Security: Multi-factor Authentication

  • Notifications: Email Notifications

  • Display: Theme

Rooms in Mattermost

When you log in for the first time, you’ll be added to the most important rooms. There may be more that you can find and join freely later.

Here’s the most important rooms for you to join and know:

Town Square (~town-square) is our public room, linked to our IRC channel. Please default to using this room for any development conversations, so anyone joining via IRC can see and join in.

Warning

Because Town Square is bridged to IRC, deleting a message will not actually delete it from the room history altogether. What you say, you cannot take back.

Water Cooler (~water-cooler) is a staff-only chatroom. Use this for general conversations that we don’t want to have in public.

Sprint (~sprint) is a staff-only room for sprint planning and discussion.

Off Topic (~off-topic) is for random chat-chat that doesn’t really relate to work.

ECO (~eco) is for any questions you want to bring up with ECO, but which you don’t necessary need to keep confidential from other staff. (If you want a private conversation, feel free to email eco@mousepawmedia.com instead.)

IT (~it) is for reporting any problems with the staff network, including email.

Hardware (~hardware) is for discussing problems with your computer, operating system, and the like.

Last, but not least, you can private message anyone through Mattermost.

Important

Post a message in ~town-square introducing yourself.

Phabricator

Phabricator is where most of our development work takes place. It hosts our repositories, task tracker, knowledge base, and wiki.

Phabricator is MASSIVE, so which apps you use depend heavily on what you’re doing. There are six major apps you should be making frequent use of:

  • Phame: Development journals

  • Maniphest: Issue tracking

  • Projects: Sprint planning (Workboards)

  • Differential: Code review

  • Phriction: Wiki

  • Ponder: Question & Answer

  • Pholio: Graphics review

All of these apps (and more) are on the left side of the main page of Phabricator.

Adjusting Settings

To get the most out of Phabricator, you should adjust some settings and fill out your profile. Follow these instructions…

  1. Log into Phabricator using your company (LDAP) credentials.

  2. Click your profile picture in the upper-right corner.

  3. On that page, click Manage and Edit Profile.

  4. Fill out as much of the profile as you want/can. Have fun with this!

Note

Please fill out at least five “Fun Stuff” fields, as this is what we will use to craft your profile on the MousePaw Media website.

  1. Click Save Profile at the bottom.

  2. Click Edit Settings at right. Alternatively, click your icon picture at the top of the page and select Settings.

  3. Select Account at left, and set Pronoun appropriately. Click Save Changes.

  4. Click Notifications at left. Select the option Web and Desktop, and save. Then, click Enable Desktop Notifications. You may consider clicking Send Test Notification in the upper-right corner to test. Then, click Save Preference.

  5. Click External Accounts at left. Add your GitHub account.

    Click Save Changes.

Important

You should also add your company email address to your GitHub account, so you can get public credit for your contributions to our repositories.

  1. We strongly recommend adding Multi-Factor Autentication to your Phabricator account. Click Multi-Factor Auth at left. On your mobile device, install a trustworthy authenticator app like Microsoft Authenticator. On your work laptop, you can install Authenticator. ONLY USE ONE! (Using both requires both.) On Phabricator, click Add Auth Factor. Follow the instructions to link your authenticator app. Repeat for the other app.

  1. Click Email Preferences at left. Here, you may shut off many

email notifications by selecting the Notify option for any given item. Recommended defaults are provided, but you can adjust these to your needs.

Warning

Do NOT select “Ignore” for any notifications! All notifications are ultimately controlled by whether you’re “Subscribed” to an object.

  1. Take a few minutes to go through the rest of the settings independently. Use the menu at left to see more settings.

  2. Click Phabricator in the upper-left corner to return to the main page.

Phame

Phame is our internal blogging platform, which we use for our company newsletter and our Dev Journals.

Read The Check-In every week for the latest reminders, company news, and helpful tips.

Your personal Dev Journal is your weekly log of what you’re building and learning. Since we’re a globally distributed, remote team, this how we share progress with one another and with our supervisors. This journal is visible only to staff and trusted community members.

You must update your Dev Journal by Monday morning every week, with the following information:

  • What you’ve done over the past week,

  • What challenges you faced over the past week,

  • What you learned over the past week,

  • What you’re planning to do over the upcoming week,

  • The Phabricator object IDs or links for anything you’ve worked on (inline).

Warning

Your Dev Journal is how we track your job attendance. Be sure to post it every single week! If it is not posted on time, your hours for the week might not be counted.

Along with posting your own Dev Journal entry, read and comment on at least two other team member’s dev journal posts every week.

For more information on Phame, see Phame.

Regular Phame Tasks
  • Read “The Check-In” for the week.

  • Post your weekly entry to your own Dev Journal.

  • Read and comment on at least two other new Dev Journal entries.

Maniphest

Maniphest is our issue tracker. Just about everything you work on should have an associated Maniphest task, which you keep up to date as you work. Bigger tasks should be broken down into smaller subtasks.

You should also use the comments section of a Maniphest task to take notes and discuss issues with your teammates.

For more information on Maniphest, see Maniphest.

Regular Phame Tasks
  • Create and update tasks for everything you’re working on.

  • Report bugs and request features.

Projects

The Projects app does a lot of things, but perhaps most importantly, it hosts our Kanban boards for sprint planning and tracking. Maniphest tasks are tagged with Project tags, and then they appear on the Workboard for that project.

To see the Workboard for a project, go to Projects, click the project in question, and click Workboard. Be careful about moving tasks between columns, however, as that’s something we do as a group as part of the sprint process.

For more information on Maniphest, see Projects.

Regular Projects Tasks
  • See what tasks are selected for the current sprint on a project.

Phriction

Our central knowledge store and wiki is Phriction. This is where we keep all of our project specs, design notes, and idea documents. We also track our sprints here.

Phriction is an excellent place to share knowledge of all sorts. If you learn something useful that might be helpful to someone else, just add it!

With rare exception, anyone can edit anything on the wiki. It’s fully version tracked, so don’t be afraid to make changes. The number one rule of wiki use: don’t ask permission! Just do it.

For more information on Phriction, see Phriction.

Regular Phriction Tasks
  • Monitor pages for projects you’re involved in.

  • Maintain any specs and design notes you’re responsible for.

  • Learn and share knowledge, especially via the Resources section.

Differential

All code and text-based content that is being developed is tracked, reviewed, and discussed on Differential. Any code you write will be submitted here first to be reviewed.

If you’ve used GitHub before, this is our equivalent of a Pull Request.

For more information on Differential, see Differential.

Regular Differential Tasks
  • Submit and maintain Revisions for your code revisions.

  • Review other people’s Revisions.

Ponder

Ponder is like our own personal StackOverflow. You can ask and answer questions here. While Mattermost is highly recommended for quick questions and live conversations, Ponder is fantastic for creating a team knowledge base and solving problems asynchronously.

For more information on Ponder, see Ponder.

Regular Ponder Tasks
  • Ask questions.

  • Store collected information as you research a problem.

  • Help answer other people’s questions.

Pholio

Graphical assets, including most work produced by the Design+Production team, are uploaded to Pholio for review and discussion. We also use Pholio for user interface mockups, as well as flowcharts and diagrams from the Programming team.

A single Pholio Mock can contain multiple images, and multiple revisions thereof. Comments can be left directly on the images themselves, as well as in the comments section.

For more information on Pholio, see Pholio.

Regular Pholio Tasks
  • Submit and maintain Mocks for your graphical work.

  • Review other people’s Mocks.

Nextcloud

Nextcloud is where we store all important staff documents (see ECO: Employee Care and Opportunity), collaborate on documents, and share a lot of common non-code files.

One essential function of Nextcloud is to allow us to collaborative edit our sprint plan and sprint retrospective documents.

Additionally, if you work in the Design+Production or Content Development departments, you’ll upload most of your work to Nextcloud.

First Steps

  1. When you first log into Nextcloud, click your username in the upper-right corner and select Settings. This will take you to your profile and settings screen. Fill out your profile.

  2. At left, select Security. Start by saving your backup codes in case you lose your device. Then, enable both Nextcloud Notification and Enable TOTP. That last one will walk you through linking to one Authenticator app; we recomemend Microsoft Authenticator on your mobile device. If you don’t have a mobile, use Authenticator on your Linux machine.

  3. The Activity section allows you to customize notifications. We recommend leaving many Push notifications enabled.

If you’ll be using Nextcloud regularly, you may consider setting up the Nextcloud Client on your computer. See Installing Nextcloud Client.

Regular Nextcloud Tasks

  • Collaborative edit documents, especially sprint plans, sprint retrospectives, and standards drafts.

  • Upload work. (Content Development, Design+Production)

  • Review and proofread content files. (Content Development)

When you upload files meant to be shared, be sure to place them in the appropriate shared folder.

ECO: Employee Care and Opportunity

Our “human resources” department is called ECO, which stands for Employee Care and Opportunity.

ECO Forms

All the ECO forms you’ll need are stored on Nextcloud, in the ECO folder.

All forms must be filled out, signed by hand (including by mouse or tablet), and emailed to eco@mousepawmedia.com. You can do this either by printing and scanning the document, or digitally with Xournal++.

  • Formal Grievance: If you are unable to resolve a conflict with a co-worker via informal discussions, you may file this form within 15 days of the most recent incident.

  • Promotion Request: When you are ready to be graduate from the internship program, or otherwise be promoted to a higher seniority, you must fill out and submit this form. Interns will also need the appropriate Internship Checklist.

  • Leave of Absence Request: Any time you will be absent for a week or more, or under six hours a week in the case of an intern, you must file this request at least two days before your absence!

  • Resignation Request: If you choose to leave MousePaw Media, you must file a resignation request. If you’re an intern, we may choose to terminate your employment with us instead of accepting the resignation, as specified in your contract.

Management Forms

There are a few more ECO forms which are accessible only to management.

  • Hiring Checklist: When we are reviewing an applicant for our internship program, we use this form to collect and track all the relevant information about them.

  • Employee Disciplinary Warning Notice: For serious and/or recurring problems, a supervisor may detail the incident and the expected remedy using this form. If you receive one, be sure to read it, initial and sign it, and send it back via e-mail ASAP.

  • Employee Termination: In the rare and unfortunate case where an employee must be fired, we use this form. There is also a separate Internship Termination form.

Next Steps

Previous MousePaw Media graduates have written up some tips for new interns! You can read those on the Phabricator Phriction wiki at the link below:

Important

Read Internship Tips

You can learn more about the different parts of the Staff Network in the other sections of this documentation.

If you’re an intern, you can find a list of all your assignments on the appropriate Internship Checklist at the bottom of the Assignments Phriction page.

Programmers should check out these sections next:

Content Developers should check out this section next:

Design+Production and Mass Communication staff should check out this section next: