7 Tools

We do reproducible products. If it works once, it must work all the time, on Windows, Mac, Linux, in Word, PDF, html, using a laptop, a cloud server, a smartphone or a table.

  • We use Keybase for internal communication

  • We are slowly bringing everybody on board with Git for online collaboration and file syncing. For a short time, we’ll still use Google Docs.

If you work with us, you must adhere to the Contributor Covenant

The pledge starts with these paragraphs:

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. Please, take the time to read once the entire pledge.

7.1 Internal communication & collaboration

7.1.1 Keybase

No more long emails. Nobody’s left out. No more misunderstandings. No more waiting for feedback.

What do we need?

  • A simple-to-use communication tool where you can opt-in to be informed on a real time basis, or completely ignore us for days – similar to Whatsapp Group, Microsoft Teams, Google Hangout, Slack;

  • A single, secure storage for shared documents – similar to Google Drive, Microsoft One Drive, Dropbox;

  • An integration with Github – a critical feature to at least the part of our team that is working on software code or long-form technical documentations;

  • Ability to oversee communications with more than 50 people with an option to streamline per topic, group, etc.;

  • To avoid using emails boxes, Whatsapp, Viber, etc. – part-timers are not flooded with messages at all times, while full-timers can reach out to each other at any time;

  • A space where we can communicate all the time without interrupting calls and meetings with clients on other platforms; An integration to a project management tool that we will use for larger projects;

  • A tool as simple as possible, light touch;

  • Since we work in the open source, open data, open collaboration community, we would like to use something that is open source – but we are willing to pay for solutions.

And the winner is….KEYBASE.IO

Keybase is a very neat, simple, lightweight team management / chat / social networking application that is extremely focused on privacy, security and encryption.

Keybase Key features

  • Secure instant messaging, even with a timed self-destruction feature (e.g. for sharing passwords); Starts a Google Meet or Zoom video call natively with a single command;

  • Brings your Whatsapp chat to the more private and secure keybase chat on the fly;

  • Team chat rooms in real time. You can filter where you want to be involved, and you can always opt-out;

-K-Drive (similar to OneDrive, Google Drive, Dropbox) – only for our team, and fully encrypted; Works with Github, and it even offers a more private version of Private Github Repos, encrypted gits; An integration with other platforms; It is neat, open source, simple, clean, and usually appreciated more in the open source community than Slack, its big corporation rival.

Practical steps you need to follow to use Keybase

  1. Download & install Keybase from https://keybase.io/ on your computer.

An easy procedure. Create yourself a professional login name – similarly to a professional github account, a professional email, etc. (you cannot change the name afterwards)

  1. Once you log in to the computer, go to Devices, and Create a paper key. Write this on paper, or print it, and store it somewhere very safe (not near your computer). This to recover the access in case you lose access to all your devices.

  2. You can use Keybase simultaneously on multiple devices – Install Keybase on your smartphone, tablet or any other device. You will be guided through installation & paired with your computer.

  3. Shall you need them, you have two recovery options: the paper key and your smartphone.

  4. If your smartphone breaks down and needs a replacement, you can add from your computer your new phone and deactivate the old one.

  5. Once you are in, look up antaldaniel.

  6. After a handshake Daniel will assist your smooth transition, help you find ways to our shared files, your project’s files, and set up filters, so you are not flooded with information, while never left out, unless you choose to.

  7. Initially, we set up the following “Big teams,” as Keybase calls them, and we will send an invitation to join:

  • reprexfriends for prospective team members, friends, and hoped-for-cooperation partners – partly for people we are discreetly asking to join us, or who want to know more about some of our work and cooperate with us;
  • reprexcommunity is an open landing page for anybody, it is a public interface. If you every land there antaldaniel will take you to the appropriate, otherwise invisible team room.

Each big team has four special members for a smooth transition: Daniel and Zuzana to assist you with getting familiar with Keybase, zoombot (just type !zoom to create a Zoom call with the team members present) and meetbot (that does the same with Google Meet, !meet). Daniel will gradually withdraw from some of the teams, once their support is not needed, though each team will have at least one Reprex co-founder present. We invite everybody to at least one team, but you can sign up to as many as you like, shall you find that convenient.

  1. Whenever you are in a situation you want to ignore us (e.g. because you sit in your dayjob), just do it. If you have a smartphone, we are there, separated from your Whatsapp friends, work emails, and you can always check on us. We can always send you a secure (and even encrypted) message to get in touch, if needed. However, we will never ever bother you with long emails, Whatsapp messages and other annoying things.

Let’s keep things short, give access to the full picture when needed, and let you find out what mix of response time, details and filters works best for you.

7.1.2 Git & Github

Git is a simultaneous collaboration for for any distributed team work - writing, programming, design work. Git is an open source software which makes sure that your teamwork files are always synchronized, clashes are avoided (you modify the same part of a file at the same time with Daniel.) The only hard part to move to Git is to make sure that Git properly works on your computer - it needs to be installed differently on all Linux distros, Mac OSX version all Windows versions. On Windows, you must make sure that Git is on the startup path. Once you are there, you’ll life will be much easier.

  • Keybase allows the group work on encrypted documents, like business proposals simultaneously using Git synch.

  • RStudio allows us to work simultaneously on business proposals, blog posts, templates via Git.

  • Github is allows us to use shared folders (repositories or simply repos) where we can track changes, modify the same thing at the same time, avoid or resolve conflicting edits, assign tasks, and much more.

If you do not have a github account yet, please, sign up now on github.com. Create a very professional profile. It is likely that you will use this profile for future works for decades, as Git is really becoming the norm of digital nomads, freelancers, and tech teams to work together.

Github is not the only service platform that allows distributed, collaborative teamwork. It has many alternatives, for example, GitLab – don’t confuse them. We use Github.

  • dataobservatory-eu is our private repo collection and private github collaboration platform.

7.2 Basic file management

If you work across different systems, like Windows 10, Mac, Linux, cloud, than you will easily get a problem with certain file names. Windows uses its own extensions, and does not like space in certain parts of the full filename.

What is a filename:

For example:

C:\data\my-file.jpg

  • has a path C:\data\
  • a filename my-file
  • and an extension: .jpg.

Paths work differently on all systems, so we try to work with relative path instead of full path. For example, all pictures used to illustrate this book are stored in the dataobservatory-eu/teambook repo (folder) and the images subfolder.

  1. Make sure that you use only relative path when you work collaboratively.

  2. The reason why we prefer markdown files is that they are platform independent, simple, clean text files, that can be translated to Windows, Mac, Linux specific files.

  3. Use filenames with snake_case_formatting_without_space.txt or snake-case-formatting-with-dash.jpg. Never use space in a filename, and if possible, avoid the use of uppercase.

  4. The extension is just information for the computer how to handle the file. An if you use an .txt extension for a markdown file, it will be still editable, but misleading. The .md extension just says that preferable open it with a Markdown Editor, like RStudio or stackedit.io.

If you create new content, try to put it into one, single markdown.md or markdown.Rmd file.

For complex documents, like this Teambook itself, we use separate files per chapter. To make sure that they can be ‘kintted’ together into a single document, they must follow specifications.

  • They must have the right filename
  • Must be placed to the right folder
  • May have a YAML header with further options (like adding a table of contents)

Let the repo editor put your single file to the right place.

  1. Put your file to drafts/draft.md
  2. Make sure that the image references are now ../images/draftimages/draft_01.jpg format, where ../ tells the computer to go to the folder above drafts.

7.3 Writing, blogging

7.3.1 Markdown

Markdown is a simple “language,” or rather a writing notation system that lets the word processor know that *italics* means italics, or **bold** means bold or ## Writing, blogging becomes a level 2 heading, and ### Markdown {#markdown} is a level 3 heading that can be referenced in the table of contents or internal hypertext links with [Jump to markdown introduction](#markdown).

Markdown makes it possible that we can work on documents that will render fine in html, docs, pptx, pdf, google docs, or md for markdown files.

Markdown is a “markup language.” But that is a too big word. It is more of a notation system for writing clear text that later can be automatically formatted.

For example [Introduction to RMarkdown](https://rmarkdown.rstudio.com/lesson-1.html) creates the hypertext link Introduction to RMarkdown in html, docs, pptx, pdf, iWork Keynote, xlsx or any file format that we need to create.

Markdown is very important for reproducible research and automation. It makes sure that the content and the form is fully separated.

  • It is always the computer’s task to make the formatting work perfectly and beautifully.

  • It is sometimes the computer’s task to fill out the document with text and numbers.

  • It is a human task to desnbng beautiful documents, like blogposts, business proposals, research reports that are very easy to replicate automatically.

Markdown is not strictly a language, and it has many ‘flavors’ or notation version. The differences are usually related to the programming interface that allows the file conversion. If you are new to markdown, you can start with any flavor, the main text functions are the same.

  • StackEdit is a wonderful tool, and we would recommend it, if it would not have been suspended from the Google Drive integration. You can try it out online. It is probably the cleanest interface to get you started.

  • Heroku Markdown Editor integrates reasonably easily to your Google Drive. This means that you can edit our blogposts in your Google Documents.

  • Docs to Markdown translates your Google Docs to Markdown. However, you must link your own images via a valid path.

  • RStudio is our preferred offline application. It integrates seamlessly with Github. It is an integrated programming environment with four panels. If you use it as a markdown text editor, you can just minimize or close the programming tools.

RStudio uses the Rmarkdown, a special version of markdown, where you can insert little programs in R, Python, C++, SQL, D3 or Bash scripts. For example, you can write a blogpost that retrieves data with a little program written by our musicology team from Spotify, or embeds a YouTube video, etc. The code chunks are visually separated from the proposal or blog post text, and you can ignore it if you do not yet write code.