Building a Knowledge Base with Codemarks

planteater edited this page Dec 6, 2018 · 22 revisions

Codemarks are living links between all the information behind your code - issues, frequently asked questions, important decisions - and the code itself. A codemark captures a discussion about a block of code, and remains anchored to the code so that the discussion can be surfaced later.

Codemark Hover

Ask a question. Help a teammate. Identify issues. Codemarks are flexible tools for simplifying your workflow. But, the real power lies in the knowledge base that they collectively represent, and that gets built up effortlessly over time.

Read on to learn how to create codemarks, and how to leverage the knowledge base they represent.

Creating a codemark

Creating a codemark by selecting a block of code in your editor and then typing a question or comment. The New Codemark form will automatically pop up (although you can turn this behavior off). Keep in mind that, unlike with other solutions, you can discuss any line of code in any source file at any time, even if it’s code that you just typed into your editor and haven’t yet saved or committed. Get instant feedback form your teammates without having to go through a formal process.

New Codemark

Select a conversation in which the codemark should be shared, pick a color for the codemark’s icon (e.g., your team can give different colors different meanings), and then, importantly, decide what type of codemark you want to create.

Comment

The all-purpose codemark for linking any type of discussion to a block of code.

Comment

Some examples are...

  • Ask a question. Leverage your teammates’ knowledge to get help with code you’re struggling with, trying to debug, or simply trying to understand.
  • Document important or complex areas of code. Unlike inline comments, codemarks are conversational. You can clarify, add additional commentary, reply, @mention, and all of the usual interactions you typically use in modern chat services.
  • Point or direct a teammate to some code. We all get asked where a specific piece of code is or where some behavior or feature is implemented. With codemarks, you can very quickly and easily provide a direct link to that code all directly from your editor.

Issue

When something needs to get done, either by you or someone else on the team, there’s always a better chance of it happening in a timely fashion (or at all!) if it’s captured as an issue.

Issue

  • See a problem with an implementation? Assign an issue to get it changed.
  • Debugging some specific issue and find more (maybe unrelated) bugs? Quickly select the offending code and create a codemark to make sure these bugs won’t go untracked and you can get back to focusing on the original issue.
  • Need some code reviewed? Assign a specific reviewer, and discuss feedback in the thread.
  • Remind yourself to come back and fix something by assigning yourself an issue instead of adding an inline “FIXME” comment.

Note that issues don’t have to be tied to a specific block of code.

Trap

Are there important blocks of code that you don’t want to be touched without you knowing about it? Maybe some mission-critical code related to security, payments or privacy? Create a trap to let other developers know to come talk to you before making any changes.

Trap

Bookmark

Highlight notable or important parts of the code, or simply parts you want to be able to get back to quickly.

Bookmark

  • Bookmark blocks of code you update frequently for quick access.
  • Implementing a feature with many code touch-points? Leave yourself bookmarks with the pieces left to be done.
  • Working with a junior developer or one unfamiliar with how a bug or feature should be fixed or implemented? Share bookmarks with them to note the places in the code to look or where parts of the feature should be implemented.

Who can see my codemarks?

When you create a codemark you select a channel or direct message in which to share it.

Post To

Your channel/DM selection will determine not just who sees the codemark when it is initially shared, but also who can find and reference it in the future. The goal with CodeStream is to build a knowledge base for your team, so it’s always best to select a public channel whenever possible. This allows the broadest set of people to leverage the knowledge base that the codemarks represent.

If you signed up for CodeStream using Slack, the channels you see in CodeStream are your those from your Slack workspace and any codemarks you post on CodeStream can be read, and replied to, from Slack.

How are codemarks discovered?

Codemarks will appear in the stream of whichever channel/DM they were posted to. In time, of course, they’ll scroll off the top of the page as new messages are posted, and scrolling back in time in a chat stream obviously isn’t an efficient way to find them. CodeStream provides three additional ways to discover codemarks.

Source File Annotations

Codemarks are displayed as annotations to your source files, with an icon (based on the type of codemark) displayed right next to the code block to which they refer.

Annotations

These annotations ensure that the right person sees relevant codemarks at exactly the right time and place. Whether you’re about to debug, rewrite, or review, the annotations in the source file will make you immediately aware of past discussions about the code, and reviewing those discussions will give you context to shape the work at hand.

Hover over a codemark’s icon and then click, and you'll be taken into the discussion thread.

Browse

Click on the Codemarks tab to explore your team’s entire knowledge base. Sometimes you might want to quickly review all of the codemarks in a given file, or all of the codemarks of a certain type.

Codemarks Tab

As you move from file to file in your source tree, the “In This File” section summarizes the codemarks in the currently selected file. And to make sure you’re always aware of what’s on your plate, the “Open Issues Assigned to Me” section lists any open issues assigned to you.

Search

Look for the search icon at the top-right of the page to search for codemarks based on a keyword.

Search

Leveraging Your Knowledge Base

As you can see from the examples above, the use cases for codemarks are endless. However, when you combine the different codemarks types with your ability to share to different audiences (i.e., channels), and even the ability to label them with colors, you can start to think of more ambitious goals for your team’s knowledge base.

Lightweight continuous code review

Establish a policy among your team of continuous informal code review. Getting more eyes on more code, earlier in the process, will lead to better code and a more efficient development team.

Faster onboarding of new developers

Of course they’ll have all of the team’s codemarks to leverage as they get to know the codebase, but you can take this a step further by creating a channel specifically for new developers where you post a set of codemarks that walk them through key sections of the code.

Create living documentation for your code

New developers aren’t the only ones who can benefit from code that comes with well thought out documentation, especially when that documentation lives and evolves via discussion among the team. Codemarks throughout the codebase can serve as guideposts that make it easier for developers to work in different parts of the code.

Identify and protect important areas of the codebase

While any developer can create code traps around blocks of code that are important to them, you might want to take a more proactive approach and identify critical parts of the entire codebase. Maybe even color code the traps to represent something about why the code is critical and shouldn’t be touched without discussion (e.g., red for code related to security, green for billing/payments, etc.).

Connect related parts of the code

“If you make a change here, be sure to also update these other two places in the code.” Does that apply to your codebase? Ensure that those “other” places in the code always get updated by tying a set of codemarks together in a single thread. Create a codemark at the first block of code indicating that changes here also require changes elsewhere. Then, create codemarks at those other locations and make those codemarks replies to the first one. That way they’re all tied together, and a developer can click on each one to jump to all the relevant areas of the code.

These are just some examples of how your team can leverage codemarks, and the knowledge base in general. No doubt your team will come up with many more, and we hope you’ll share them with us!

Ready to install CodeStream?

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.