2019-04-12 11:23

Open source policy

Recently I helped an organization to formulate its open source policy. I'm now open-sourcing this policy ;-).


Our organization is using open source projects in our own products.

It's only natural that we also contribute back to the open source community!

This document discusses the guidelines that apply to open sourcing code, documents, or visuals.

What can be open sourced?

  • Code
  • Visuals and designs (examples: icon libraries or fonts)
  • Documents (examples: best practices, coding style guidelines)

This documents focuses on open sourcing code. Some principles also apply to visuals and documents, only the license will be different.

When does it make sense to open source your code?

  1. Your code is usable outside our company: there is a clear "value" for other developers.
  2. Your code has good test coverage.
  3. Your code is well-documented.
  4. Your code is relatively small (not much larger than, say, 3000 lines of code).
  5. Your code is not dependent on internal systems.
  6. Your code is not making life substantially easier for direct competitors.
  7. Your code does not contain any code or libraries licensed from 3rd parties.

Ref 4) You and your team mates will have to support the code over the years and it's easier to maintain 3 KLOC than 30 KLOC. We don't have the same resources as e.g. Facebook who pays for multiple, dedicated teams to work on OSS.

Ref 5) Your code must work on its own, without needing any of our internal systems.

Ref 6) If your code would give our competitors a huge competitive advantage (e.g. it reduces their time to market to ship a competing feature) then it doesn't make sense to open source it from a commercial point-of-view.

Step 1

Ensure the thing you want to open source ticks all seven boxes mentioned above.

Step 2

  • Seek approval from the CTO or Head of Engineering to commence with step 3.
  • Decide which license structure applies. In all but exceptional cases it will be the MIT license. See this article for an overview of the license considerations.

Step 3

  • Write an awesome readme. See https://github.com/matiassingers/awesome-readme for examples and inspiration.
  • Check your test coverage. Improve if needed.
  • Check your documentation. Improve if needed.
  • Ensure no customer names, keys, secrets, et cetera are present in your source code (which should never be the case btw!).

Step 4

Choose a "safe" name for your project. With safe I mean:

  • Check if the name doesn't yet exist on GitHub, GitLab, or elsewhere as an open source package.
  • Check if the name doesn't yield tons of non-technology related results on Google.
  • Ask your colleagues for suggestions.

Step 5

  • Commit your work to a new, (initially!) private GitHub repository.
  • Ask your team mates for a thorough code/documentation review.
  • Ask the CTO/HoE to review the files.
  • The CTO/HoE will give the final thumbs up to make the repo public.

Step 6

  • Set a monthly (preferably weekly) reminder in your calendar, or subscribe to GitHub notifications, to stay on top of issues reported by the community.

Tip: don't fork this project in order to use a different version of the code in our products. It's much better to use the code as-is to ensure constant improvements originating from our own use.

§ Permalink

ξ Comments? Kudos? Find me on Twitter

2019-04-10 16:31

Hello new blog

For a long time I looked for an easy way to maintain a blog. I looked at Hugo, Jekyll, Middleman, and Nanoc. All great, versatile tools but still too heavy for my basic needs.


  • Git-based.
  • Command-line based.
  • Static self-contained HTML files.
  • Adding a new blog post consists of creating a Markdown file.
  • Occasionally I want to post (or rather "recycle") a snippet or a random thought stored in a GitHub Gist.
  • Sometimes I post a bunch of tweets ("tweetstorm") which I like to use as a blog post.

To scratch this itch I developed a basic blog publishing tool called MsgTrail. The source code can be found here.

MsgTrail has the following features:

  • Content sources:
    • Local Markdown files.
    • GitHub Gists.
    • Tweets including support for tweetstorm stitching.
  • User interface: command line.
  • End result: self-contained HTML.
  • Hosting: no (bring your own).
  • Search: no (rudimentary support for Google's site: feature).
  • Archive page: yes.
  • Feed: yes (Atom).

Check out the documentation on how to install and use MsgTrail.

I use MsgTrail to maintain this blog. The source code of the msgtrail.com blog can be found here.

§ Permalink

ξ Comments? Kudos? Find me on Twitter

2019-03-17 08:37

Learnings from past mistakes

[1/4] While working on a document I asked myself this question: What have you learned from past mistakes? Note: context = company building.


[2/4] - Make something people want ("YC") - Speed and design of UX is key - Product should have built-in viral aspect - Keep costs low - First 10 hires determine outcome


[3/4] - Ship fast - Start marketing on day 1 - Make continual, gentle course corrections on product, pitch, and positioning - Listen carefully to customers - Act internationally from day 1


[4/4] - Constantly test price elasticity - Rely on content marketing extensively - Pay experts to explore hundreds of SEO approaches guides by own intuition - Sales struggles should never last more than 6 months - Set ambitious goals, but avoid perpetual crunch time


§ Permalink

ξ Comments? Kudos? Find me on Twitter

2019-03-15 22:02

On remote software development


Around 2006 I started working with remote software development teams. In all but one case it has always been enjoyable, and successful from a business perspective.

I've worked with folks from Bolivia, Bulgaria, Costa Rica, Croatia, Estonia, France, Germany, Hong Kong, Hungary, Lithuania, Poland, Portugal, Spain, The Netherlands, UK, and US. The working language has been English in all cases.

To make remote working successful the first step is to hire relatively senior people. I don't mean senior in age per se, but in working experience, level of confidence in their abilities as a developer, experience in remote working, and grounded in terms of having settled in a city for a couple of years. It's OK if you don't tick all the boxes, but ticking just one is a sign you've perhaps not reached the necessary state of "balance" required to take on the responsibilities as a remote engineer.

Assuming you have the right people in place, how do you enable your team to achieve a high degree of effectiveness, pleasant collaboration, and velocity, yielding a constant stream of solid deliverables?

Outlined below you'll find my recipe for remote team success:

Yesterday I... Today I...

Tell your team members what you worked on the previous working day and what you're planning to do today. Post this to e.g. Slack first thing in the morning.

Example of a posting:

Yesterday I worked on writing a test data script. I used a fake/random data generator to create database records for all attributes of all models in our schema. Today I am going to refine this script by ensuring all (model) states are represented by the script. If you're interested, check out this draft PR. There's an issue with my VPN which I'd like to address during the stand-up.

Keep your posting short by leaving out details which don't contribute to getting the most important points across. You and your team mates will have a good status overview if you all start your mornings by writing and reading these postings.


Hold a 30-minute stand-up each day to discuss anything that needs the additional "bandwidth" obtained by talking to your team mates via a (video) call.

The stand-up doesn't necessarily have to be in the morning. I've worked with teams who make a status posting in the morning, dive straight into 5-6 hours of coding, and reconvene around 16:00 for the daily stand-up. For other teams it might work better to hold the stand-up in the morning.

If you often overrun the allocated time then it's time to appoint yourself or someone else as a "chair(wo)man" who politely cuts off long-winded discussions, asking folks to pick up the conversation outside the stand-up in 1:1 calls.

Pick the right channel

Make sure you have a common understanding in your team about the communication channels you're all using. Suppose your team uses the following channels: chat, email, (video) calls, screen-sharing, and SMS/texting. Discuss the "priority" of each channel to ensure everyone understands when to use which channel.

For example: make chat (e.g. Slack) your primary channel, used for status updates and asking questions throughout the day. It's OK to use it in asynchronous way (more on this below).

The next channel can be voice via audio & video calls. Use it to discuss complex topics that require a spoken conversation. Use screen-sharing to discuss code or a user interface.

The third channel can be email to communicate with external folks such as customers, suppliers, investors, etc.

Finally, use SMS or a texting app like Signal or Telegram to notify the (Ops) team about critical stuff such as infrastructure outages.

Chat... responsibly

Don't trade a noisy office for noisy communications. For instance, if you use Slack make sure to only create a handful of common channels which all team members are expected to subscribe to. All other public channels can be joined, left, and muted at will. Try to avoid setting up lots of private channels because there's hardly any information that can't be shared with all team members.

Do not expect people to respond immediately to everything you post. If it takes two hours before you get a reply then that's fine. People are supposed to be heads down, working on stuff.

Ask particularly "chatty" people whose conversations have a bad signal/noise ratio to improve the way they communicate.

The Five Hour-rule

Insist on having at least five hours of uninterrupted time during which you can code, write, design, et cetera. Schedule your stand-up, calls, and meetings outside these five hours. Even if your personal work rhythm doesn't fit the 5-hour agreement, it's good to have a common understanding in your team that everyone can be heads down for a considerable length of time.

Measure performance

Measure team member performance mainly on output. It doesn't matter when they work, how long they work, whether they work in long stretches or short bursts, all this is irrelevant (plus: everyone is different).

The only thing that counts is what a team member delivers in terms of code, designs, texts, et cetera. Team leads should take time to review and discuss work when needed. Code reviews are a great way to look at the deliverables of developers.

In the case of designs and copywriting you should always ask the creator: "do you want a 20% done or 80% done review?". Based on the answer you know what kind of feedback you should give.

Don't measure bullshit

Related to the previous point: do not measure performance based on the number of messages someone posts, how quickly they respond to emails, or how quickly they pick up the phone or return a call.

Work predictable hours

In case your team is located in the roughly same timezone (+/- 2 hours) then you should try to stick to "office hours" e.g. starting between 8:00 and 10:00 and ending roughly eight hours later. This makes it easier to schedule stand-ups, deal with issues that have arisen throughout the night, and to instill a sense of a normal work rhythm.

Show commitment

Perhaps sounding slightly contrarian to the previous points, it is important to instill a sense of proper work ethics in your team. If you write "taking a long walk to clear my head" then also add "will make up for lost time tonight". If you post "traveling to Oslo today" then also add "will catch up with project x on Sunday". Being in control of your own time does not mean it's OK to goof off excessively.

Use precise language

Be precise and comprehensive in your questions and answers. Working with a remote team in many cases means working with non-native English speakers. Combined with a lot of writing instead of calling, it increases the chance of misunderstandings.

For example, if you ask "Hey Jane, can you check our SSL certificate please?" then the answer could be "Yes", or "Yes, it's still valid". A better answer would be "I've looked at the SSL certificate for example.com. It's valid until 2019-03-28. I have just subscribed myself to reminder email notifications. I will take care of extending it well before it expires.".

By typing a few more words the person who responded 1) confirms the domain name (which the asker forgot to mention in his question, the replier makes up for this deficiency), 2) she mentions the exact expiration data, and 3) she takes ownership of the problem.

Accumulate decisions

Especially in fast-moving startups a lot of decisions are made throughout the day. While you can't and shouldn't involve all team members in all decisions, the bigger decisions should be discussed with the whole team.

Instead of paging the whole team the moment you would like to make a decision it's often better to save it up for the next day. Write down the rationale about the decision you wish to make, and post it to Slack.

This enables the team to noodle on it for a bit. Discuss the decision during tomorrow's standup. If you need to make many decisions, over the course of several days, then it's best to write the decisions (and rationales) down and call for a meeting to discuss and rubberstamp them all in one go.

Be kind

Say "please" often and use emoticons 👍🏻👌🏻❤️ judiciously. This keeps the conversations civilized and adds a touch of humor, tongue-in-cheek, self-mockery, et cetera.

Use video

Use video calls to "see the whites of their eye". It's easy to bury yourself in code, designs, chat, and emails, causing you to forget that your team mates are human beings of flesh and blood. Call them up, look into their eyes while you discuss something. Eyes are the mirror of the soul. Make use of this fact.

Use screen sharing

Use screen sharing. This ten times. Screen sharing is an incredibly powerful tool to discuss user UI designs and UX flows, to do pair debugging, or even pair programming (albeit for programming you should not only share you screen but also your mouse and keyboard – there are many options). Record your screen sharing sessions and post it to Slack allowing team members to catch up at their own leisure.

Make it easy to take time off

Even though remote work might be less stressful than commuting into an office every day, it's still important that your team members take frequent short and occasional longer breaks throughout the year.

Make it easy to request and take vacations. I often propose this simple rule: if you want to take a day off, try to arrange it with your team one week before. In the same vein: want to take a week off? Discuss it a month before. Taking an extended break of several weeks? Try to plan it at the beginning of the year for all team members. In this way you're not down to less than a skeleton crew during the summer holidays.

Your team is not your family

Your team consists of kind individuals but they are not your family. Businesses that describe themselves as "one big family" confuse the professional relationships between co-workers with the relationship between you, your friends, and your family.

Working on this relationship is important though, and mainly grows by closely working together on your product. It's also good to go out occasionally for diner or drinks but don't force people to participate, and don't make it a weekly thing because people have a life outside the company.

Mix remote/local with care

From personal experience the following works well: a fully remote development team, while the rest of the company (sales, support, marketing, management) works from one or more offices. The benefit of having a fully remote dev team is that all members are put at the same "disadvantage". What also worked for me is a fully remote team, including all non-technical roles.

Prevent pet project pushing

When everyone's working from the same office it is easy to notice that someone frequently discusses his favorite missing features with developers. Product owners usually shoo them away, insisting they submit their wishes via the proper channel. In a remote team every developer is just one direct message away. Make sure your whole team insists on declining direct invitations for "quick questions".

Comments or feedback? Let me know on Twitter

§ Permalink

ξ Comments? Kudos? Find me on Twitter