Disseminating engineering knowledge tidbits with tip-of-the-week articles

To keep up with the rapid growth Lucid is experiencing, we've significantly increased the size of our engineering team. Many new engineers are onboarded each year and we have now reached the size where not all engineers know each other personally. While this growth is exciting, it poses some structural challenges for us. One of those challenges is figuring out how to effectively disseminate information throughout our moderately-sized and growing engineering organization.

In Lucid’s early days, our engineering team was small enough that every engineer knew and often talked to all the others. Disseminating knowledge throughout the whole engineering team was pretty easy. Most of it could be done through face-to-face conversations or code reviews. However, as the size of the organization grew, these channels became less effective. That’s why we’ve introduced our own internal “Tip-of-the-week” articles. 

Our basic information dissemination strategies

The tech talk is a tried and true strategy used throughout the industry to circulate relevant information. The typical format is an hour-long presentation led by one engineer on a specific subject. For example, we’ve had tech talks on writing secure code, backwards compatibility issues, and strategies for writing great automated tests, among many others.

Our tech talks are a weekly event, and are a valuable channel for sharing useful information throughout the engineering organization. Recordings of each talk are posted internally so engineers can access them at any time.

Language- and domain-specific documentation is another effective approach to disseminate engineering information. At Lucid, we utilize many different technologies such as, TypeScript, Angular, CSS, Scala, Play Framework, Bazel, and more. Our internal wiki articles contain best practices for how we use these technologies across the organization. These articles are useful for code reviewers because when they see a violation of a best practice in a pull request they can just link to the relevant article.

Chat channels and forums are a large part of our information dissemination strategy at Lucid. Currently we use Slack as our chat program. Slack supports channels, and we have created dedicated channels for each of the major technologies we use. When someone has information to share about one of these technologies, they usually drop a message about it in the corresponding Slack channel. Now it’s easy to  search the chat archives to find old messages that reference the info you’re looking for.

Problems with our basic strategies

The basic strategies we discussed are effective for many cases, but there are several relevant issues that need to be resolved.

One challenge with our basic strategy as described so far is that there is a vault of information and it can take a long time to consume. For example, it is unreasonable to expect a new-hire to watch all the entire archive of tech talks, or thoroughly  read all of the internal documentation for our current tech stack. And they certainly can’t go back through the complete history of any chat channel.

Additionally, there are knowledge gaps within these information stores. For example, if there’s a small tip for a specific integrated development environment that could significantly improve an engineer’s productivity, where do we put that tip? We probably don’t want to make a whole tech talk for a single piece of advice and it would be difficult to find if we stored it somewhere else.

Finally, people don’t know what they don’t know. If an engineer knows what they’re looking for, then it’s pretty easy to find any information about it in the places we already mentioned. But if they don’t know a technique or technology exists to solve the problem they’re encountering, how would they know to look for it.

At Lucid we have a handy Angular directive for collecting analytics data when a user clicks on a GUI component. If an engineer doesn’t know about this directive, they will likely go through the annoying process of registering new analytic fields and writing unnecessary boilerplate code to get the info that would be more easily obtained by attaching our helper directive to their component.

Introducing Tip-of-the-Week Articles

Last year at Lucid, to counter many of the deficiencies in our basic strategy we began a series of “Tip-of-the-week” articles. The idea was inspired (name and all) by a similar series of internal articles at Google that have been published for years. The goal for each article is to introduce one simple tip for the benefit of our engineers at Lucid. These tips should be based on established best-practices and not new or controversial topics.

One Lucid engineer acts as the editor-in-chief of the series. Their responsibility is to curate the collection. Editors need to solicit article topics and then find experts to author and review the articles for each topic. After an article is written and published the editor-in-chief keeps track of any information that falls out of date. If a whole tip no longer applies because of a change to engineering practices, the editor can mark a whole article as obsolete. When only part of a tip gets out-of-date, the editor can insert footnotes or other notifications to notify readers of the current best practices.

When choosing topics for articles we look for three main qualities:

1. It should be impactful.
2. It should be short (fitting on one printed page, if possible).
3. It should be uncontroversial.

Impactful

We want to focus on tips that are widely applicable. If a common question or a bad pattern comes up over and over again in code reviews, we make that a topic for a Tip-of-the-week article. If there is some useful tip that doesn’t fit well into one of the other methods of information dissemination, that is also a good candidate for a Tip-of-the-week article.

Short

Consumability is one of the main obstacles with our current information sources, and Tip-of-the-Week aims to directly combat that problem. That means it needs to be as succinct as possible. Ideally, engineers should be able to review the complete Tip-of-the-week archive and identify the main topic of each article. This helps our engineers learn and stay up-to-date on relevant practices. At Lucid, we expect new hires to review older Tip-of-the-week articles.

To keep articles short, we encourage authors to include links to additional relevant documentation for the given tip. Even if the article doesn’t answer every question an engineer may have, it can point them in the right direction. 

Uncontroversial

Tip-of-the-week  articles are meant to disseminate information on established best practices. The editor-in-chief will likely receive submissions regarding the use of untried technologies. After all, people are excited to talk and write about those kinds of things. But that is not the purpose of Tip-of-the-Week. Tip-of-the-Week is an intentionally narrow channel, and you don’t want less relevant information to take up space in that channel.

Articles should not ignite unhealthy debates or disagreements. For example, you definitely don’t want to promote a side on the question of vi vs emacs. Instead, stick to things that everyone can agree on. There are certainly enough impactful uncontroversial topics that you don’t need to stray outside of that realm.

Try it yourself

If you are in a large or growing organization that is suffering from a difficulty in disseminating one-off development tips, you too should consider creating a Tip-of-the-Week column. We recommend starting with a meeting of your senior engineers and technology experts to create a list of important topics to cover. For example, you could create a Lucidspark document for a brainstorming session and use the voting feature to identify the best topics to start with.

The Tip-of-the-Week column has been a huge success at Lucid. Every week, we get grateful comments from engineers like, “I didn’t know that I needed to know that.” It takes a significant amount of work to curate the articles, but so far the payoff has been well worth it.