Three months ago, we decided to pivot.

We had set out to build a modern version of a wiki to help engineers share knowledge better. But after some time, we realized that we weren’t serving our users’ real workflows. We were building for an idyllic version of knowledge sharing that no one really followed.

So we decided to do some more user research. We discovered something fascinating. While engineers didn’t post to wikis as often as we wanted to believe, they write tons of private notes.

Engineers start by jotting things down in Apple Notes (or similar). Then they often copy-paste notes from their Apple Notes into other tools in order to organize and share. Apple Notes, Google Keep, and raw text files give the best jot-down experience, but they fall short for organizing and collaborating. …


Image for post
Image for post

According to legend, Thomas Holley invented the first legal pad in 1888.

At the time, he was working at a paper mill in Massachusetts. He had the idea to stitch together the leftover paper and sell it as a cheaper notepad.

Holley then went off to start a business making these substandard pads. And the legal pad was born. The first pads Holley sold were actually white. And no one is sure why it became yellow. One theory is that it was difficult to bleach the substandard paper. And it was easier to make the pads darker instead. …


Image for post
Image for post

We started Bytebase with the belief that the note-taking systems we rely on are too formal. When it comes to writing notes, the first order of business is to just get it down.

Too often, friction gets in the way of jotting notes down. Obstacles might come from the shortcomings of our note-taking tool, or from the rules of the note-taking methodology we’re trying to adhere to. Each obstacle makes it a little less likely that we write something down that we’ll wish we had later.

It is tempting to imagine what an optimal practice might look like, whether it’s note-taking or something else. We envision a dream scenario, like pristine notes, or the physique of a Greek god. Then we construct an elaborate plan for achieving that outcome. We set out with the intention of following through, but we lack the determination and commitment to do the (always underestimated) work required to put it in practice. …


Image for post
Image for post
Photo by Noah Silliman on Unsplash

When we look to people we admire, we can recognize that they probably didn’t start this way. They had a base skillset and way of being, bu then they worked hard and adopted a can-do attitude to become who they are today.

The new Michael Jordan documentary is a great reminder of this.

Michael Jordan is widely thought to be the greatest basketball player of all time. Watching the documentary, you can see that he became great because he believed in himself. He dedicated himself to improving his game, on and off the court. …


Image for post
Image for post
A “why” doc in a Git commit message

As engineers, we write and commit code every day. Each line of code we introduce is just one small piece of a software system that’s likely to outlast the specific code we’re committing. Our goal isn’t only to ship the code today but to prepare the team to successfully add to and maintain the software system in the future.

Preparing the team for the future means making our code easy to understand by following best practices like descriptive variable names and encapsulating complexity. …


Image for post
Image for post
Photo by Emily Morter on Unsplash

Many of us have, at one time or another, blindly followed a pattern we noticed, thinking that must be the way to do it. We do so without questioning if that pattern is the best fit for our particular situation or if that pattern was ever a good idea to begin with.

In doing this, we rob ourselves of the opportunity to learn and deepen our understanding, to be intentional with our work, and, ultimately, to get better at our craft. …


Image for post
Image for post
Four strategies for writing actionable engineering docs.

A common frustration with software engineering docs is that they feel like a waste of time because they often go unused.

But there are certain pieces of knowledge that are useful and actionable to your teammates and to your future self.

Actionable docs include:
- Code commands
- Post Mortems
- Runbooks
- Decisions

After talking to dozens of engineering teams, we’ve found these four strategies help engineers write actionable docs that people actually use.

Use standardized templates.

Standardized templates make it easy for engineers on one team to dive into the work of engineers on another team. Without a standardized template, each engineer first needs to spend time getting acquainted with how the author organizes information. …


Image for post
Image for post
The Pull Request Checklist for startups.

Startups that have an effective Pull Request (PR) process can ship features faster and with higher-quality code.

The key to an effective PR process for startups is to keep items small and decide on a lightweight guideline for describing what the PR introduces.

Here we’ll go over what we’ve found works best at Bytebase.

Pull Requests (PRs) should be short and meaningful.

Short PRs lead to higher-quality code.

Short PRs lead to higher quality code because short PRs are easier to review. Instead of skimming through endless diffs, a reviewer is able to more thoroughly review a small change, making it more likely that any potential issues are identified.

Short PRs lead to faster delivery of features.

Short PRs also lead to faster delivery of features because they keep the team in a good rhythm of shipping and make it less likely that one person’s work will block another’s. A PR that makes a small change is less likely to interfere with a small change that another teammate is working on. …


This is a second post in a series adapted from the Django Real-Time Chat tutorial we presented at the 2019 US DjangoCon conference in San Diego. Here’s the code.

Part One covered why we chose WebSockets and how they work.

This post will cover:

  • the motivation for Django Channels
  • the core building blocks for Channels
  • how to build our first chat server by following the official Django Channels tutorial

If you don’t know us, Bytebase is the byte-size knowledge base for engineering teams. Bytebase supports collaborating on a module in real-time.

In this post, we share how we used Django Channels to enable our web application for Real-Time communication. …


Bytebase is a tool for team notes that’s built for speed. Everything in Bytebase is a “byte” — a short chunk of information. A byte is also a folder and a tag.

Today I want to share why we think it’s important that “folders” and “tags” are equivalent in Bytebase.

Let’s start with an example.

Taking notes on a user interview.

Suppose I am conducting user interviews. I’ll start by creating a User Interviews byte (folder) to hold my notes.

Image for post
Image for post
Create a User Interviews Byte to hold all User Interview notes.

My first User Interview is with Bob. I create a Bob from Hooli byte (folder) and record my key takeaways from our conversation in Bytebase.

Image for post
Image for post
Key takeaways from my user interview with Bob.

Organizing notes from my first user interview.

Some of my notes are feature requests and I’d like to organize them accordingly. …

About

Bytebase

This is the official blog of https://bytebase.io— the fastest way to write, organize, and collaborate on notes.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store