DEV Community: Itai Katz

NYC Meetup: Creating a single source of truth 🧘‍♀️

Itai Katz — Thu, 08 Sep 2022 19:46:40 +0000

We're hosting a meetup for the dev community in NYC

Join us on Tuesday, September 13 at 6pm for a panel discussion followed by a night of networking, pizza + drinks.

Panel includes Ashley, VP Engineering at Datadog and Etan, Software Engineer at Stripe.

Free event at the NoMo Soho. Grab your ticket here.

What's worse: Stale documentation or no documentation?

Itai Katz — Sun, 14 Aug 2022 18:12:00 +0000

Stale documentation. 1000%.

Agree?

Incident management & the wet floor sign

Itai Katz — Tue, 09 Aug 2022 11:21:00 +0000

In software engineering, incidents are occasions where critical bugs and issues are exposed in the production environment. They can be found by a user, an automated test, or an engineer. But regardless, an incident is considered a critical issue that makes its way into production without the engineering team or any test or automation noticing it beforehand.

Incidents are always a bit of a sensitive topic - whether it’s because people don’t want to admit there are issues with their code, or because they tend to expose flaws and issues in our processes that we usually don’t like to discuss.

And this is, even more the case with repeat incidents, as these would have potentially been avoidable altogether had we simply known about it. In other words, we wouldn’t have slipped on the wet floor if someone had put a warning sign up for us.

When talking about incidents, the legal concept of “Errors and Omissions Excepted” comes to mind. And as engineers, we know that mistakes happen, and they can happen again; this is quite common in the software engineering industry. We understand that people are fallible and make mistakes, and of course we should expect that. And we also assume that they have good intentions; we hope and expect that mistakes will be corrected.

Think about it: how many times have you refactored a code to avoid a bug, only to have another engineer make a similar mistake sometime later on? Or how many times have you created a hot-fix to address a certain issue, promising you’ll refactor and turn a patch into a permanent solution?

That is why we should fix these issues, add tests and processes to ensure they won’t happen again, and also document what happened and share the knowledge.

Why should developers document incidents?

The legal concept of “Errors and Omissions Excepted” is essentially a disclaimer for situations where information is rapidly changing. Therefore it can be hard to obtain and thoroughly review an accurate snapshot of it. And code is precisely that - a rapidly changing, complex to review set of information, whether it’s the code itself or its environment.

One approach is to write tests to make sure that an incident never happens again. But while tests are important and helpful, they usually look at an incident through the pinhole view of a bug in a certain line of code - which means a test will not contribute any information about how an incident happened, what needs to be done outside of the code to avoid a similar incident, and what processes and changes are needed to prevent it from happening again.

And that is why even though tests are helpful, we also need documentation.

But documentation is not free from potential issues. Because even if documentation is created about a particular issue (and that is a big if), that documentation is usually outdated, detached from the code, or hard to locate or even know about in the first place.

Here at Swimm, we’ve encountered similar issues and have created a way using some of our Swimm toolsets to try and solve all of these issues. We simply add a “Wet Floor Sign'' to code paths that might be problematic to change.

Best practices for incident response documentation

There are many ways to avoid repeating incidents, and as developers, we are highly motivated to improve our best practices for incident management.

Encourage documentation
Step 1 is to make sure to create documentation once a certain issue is discovered and fixed.

I know - encouraging engineers to create documentation is hard to do, but Swimm makes it a lot easier with the option of adding a template for Incident Reports with Swimm’s Templates.

And we have also added documentation to our Definition of Done for our hot-fix release. For example, in version 0.7.0, we had an issue where our release notes assets were not added to the correct path, and we created documentation to summarize what happened and how we fixed it.

Attach documentation to code
As part of our Definition of Done for hot-fix releases, we also recommend adding a snippet from the code that fixes the issue to the documentation. At Swimm, it’s not a requirement, but a strong recommendation.

As you can see below, we did exactly that by adding our Release Notes to the document describing the hot-fix. This is the head’s up for us, so we remember our fix and don’t slip next time.

Maintaining documentation
By adding a code snippet to an Incident Report document, you can keep track of it if someone changes the code lines that fixed a specific issue. Specifically, Swimm’s GitHub App will automatically flag the document as Auto-synced (when there’s an insignificant change) or outdated when it requires reselecting a snippet.

In our case, if someone significantly changed a code path related to the incident, they would be asked to read the doc and edit it accordingly, bringing more attention to the sensitivity of the issue. Also, if someone refactors the structure of our release notes, they should also update the documentation containing our warning and move it to the new location.

And with more minor changes, Swimm can automatically synchronize your document and commit it directly to your Pull Request.

Locate your documentation easily, right when you need it
By requesting a snippet to be added to an Incident Report document, Swimm makes it discoverable using our IDE plugin while writing code. Therefore everyone who adds a new release note sees the hot-fix documentation tagged to this object.

Furthermore, since Swimm is storing your documentation as markdown files together with your code, you can globally search for phrases such as “hotfix” or “incident,” and you’ll be able to find and read the relevant documentation without leaving the IDE. So every time someone adds a new item to our releaseNotes array, they will see there is a related doc with “Hotfix” in its title.

We also have an Incident Reports Playlist that gathers all of our reports and can help others catch up when onboarding and encountering a familiar issue. This is an important way for managers to keep tabs on reading and understanding incidents and fixes on their teams.

Also, by having our New Document Notification emails sent to Slack, you can get more people to look at new documentation that’s been added.

Bottom Line

While some incidents are unavoidable, with Swimm, you will be less likely to have the same incidents repeating themselves later on down the road and more likely to fix issues or adjust areas that have been lingering for a while

Swimm’s platform utilizes numerous tools such as our Web App, GitHub App, and IDE extensions that make it easier to work on code-coupled documentation, maintain it, and find it when you most need it.

If you’re interested in getting that assurance that your wet floor sign will be handled with Swimm’s platform, learn more about Swimm and join our open beta today. Slips and falls that are avoidable save countless hours of time and aggravation. And you’ll be able to give away your wet floor signs.

You're Continuously Integrating & Continuously Deploying. The time has come to Continuously Document.

Itai Katz — Mon, 08 Aug 2022 17:09:11 +0000

I'm Principal Software Engineer at Swimm. A startup building a documentation tool for developers based on the paradigms of Continuous Documentation.

What is continuous documentation

"Continuous documentation is the process of creating and updating documentation incrementally and as part of the development workflow, ensuring it is in sync with the codebase."

The author - who happens to be a good friend of mine - argue for 3 main principles.

Continuous Documentation means that the documentation is:

Code-coupled
Always up-to-date
Created when best

Sounds good in theory, right?

But how does it work in practice?

One way is through Git Checks
Swimm automatically checks any documentation pushed to git to make sure it’s up to date. If the code mentioned in your documentation changed, Swimm alerts you and lets you address the issue quickly and easily. This way both your code and your documentation are always accurate and up to date.

I invite you to check out Swimm and join our free open beta and I'm happy to chat with anyone from the dev.to community to show them the various use cases for Swimm - for both teams and individuals.

Should documentation be in included in the definition of done?

Itai Katz — Sun, 17 Apr 2022 14:36:14 +0000

The Definition of Done (DoD) is a shared understanding of what work must be completed for a work unit (think: user story, sprint, feature) to be released.

Why does the Definition of Done matter?

There are 3 main reasons IMO

It provides a baseline for sprint planning. If you know ahead of time what is expected in terms of testing, documenting, and deploying then you can more accurately size backlog items and thus, plan accordingly.
Avoiding repetitive conversation and redefinition. A clear DoD provides a framework for defining the tasks required for each work unit. Therefore, you can focus on execution rather than be stuck in a constant loop of defining.
Reducing the need for rework. A clear DoD limits the risk of misunderstanding and conflict among the dev team and product owners. Once a backlog item is accepted as “done”, the chance that it will need to be reworked is reduced, and required (non-critical) updates can be moved into the backlog.

The DoD doesn't happen in a vacuum

It can't focus on just building usable software. It must be aligned with the overall organization’s needs, goals, and core values. And that's why a DoD should be a collaborative process among all those involved.

Should the Definition of Done include developer documentation?

I believe this question is key. And I say yes, the DoD should include documentation.

I think it's useful to go back in time here and remember the conversations we used to have about e2d testing and whether it should be included in the DOD. And guess what. The exact same concerns were raised then.

It hasn’t taken long, though, for us to recognize that writing tests sooner rather than later has provided great value and allowed us to make significant quality advances. And as a result, end-to-end testing has become part of the DoD for a lot of developers I've spoken with.

So, what do you think? Should it become the new standard?

Wtf is Walkthrough Documentation?🤔

Itai Katz — Tue, 12 Apr 2022 09:31:13 +0000

I like to call Walkthrough Documentation the missing link between low-level & high-level documentation. And it's something that is often over looked.

But, in my opinion Walkthrough Documentation is where the value in documenting lies.

So what is Walkthrough Documentation?

This form of documentation takes readers on a guided tour of the code base. It uses code snippets to explain points of interest on the map.

As it moves from landmark to landmark, it can point out recurring patterns. It can describe interactions between different blocks of code that may reside quite far from each other or even multiple repositories

Recurring patterns in code

Repos contains patterns. For example, deriving from a base class, calling a specific API to read from a database, creating a new config value, adding a new CLI command, and the list goes on.

When a new dev joins your team, they will most probably perform one of the above mentioned tasks & will need to understand how they're done in your codebase.

This could be easy if the patterns are simple. But, more often than not patterns aren't so simple and span many different, often far away files in your codebase and can be tricky to understand on your own.

And thus, the need for Walkthrough Documentation comes into play.

Here's an example

Adding a new CLI command, specifically with git CLI. Let’s say that you want to contribute to the git project by adding the command git mycmd and you want to understand how such a pattern is achieved in git's source code.

Take a look at the git clone, a pre-existing example of said pattern. This command (along with every other command), comes with a corresponding file in the builtin/ directory (in our case builtin/clone.c) and contains the function that implements the command:

Declaring the function isn't enough: we also need to declare it in builtin.h:

Next up: "register" the command so that git knows where to find it. The way to do this is to add it to the commands list of structs detailing the commands in git.c:

And last but not least, add the command's file to our Makefile:

This explanation is tightly code-coupled and goes over specific implementation details including how to name functions, where to put files (the builtin/ dir), function signatures, how to name files (clone.c, builtin.h), variable names (BUILTIN_OBJS), etc.

The explanation walks the user through different areas of the code that are all related to the single pattern of adding a command to the CLI. This kind of highly focused tour through the code can really help the user grasp the pattern and understand it quickly.

But there are challenges.

Yes it takes time. Yes value is lost if it's not properly maintained. My colleague delves into the challenges & how you can overcome them in this article.

So, what are your thoughts on walkthrough documentation?

Gitsasters, or going back in time 🕰️

Itai Katz — Wed, 23 Feb 2022 13:02:29 +0000

My colleague/friend wrote an insightful piece on overcoming git disasters, or as we refer to them, gitsasters. I thought to give a high-level summary and invite you to check out real-life instances where the git reset tool comes in handy.

What is a gitsaster?

Understanding the concept of git can actually help you know when things go wrong. For example, when you do something you didn't mean to do and just want to go back in time- this is precisely what a gitsaster is.

Things go wrong in git all the time. There are people like myself who understand what's happening underneath the hood and thus remain calm.

But, what about those who don't have as deep an understanding? They tend to look at git like a magical black box.

Recording changes in git

I don't think a few sentences can give this topic justice. This article provides a thorough overview on recording changes in git.

But to sum it up: git doesn't commit changes directly from the working tree into the repository. Changes first get registers in the index/"staging area". You can think of the index as a way of “confirming” your changes before doing a commit.

The command git reset, together with its three modes:

--soft, that moves whatever HEAD is pointing to
--mixed, that goes on to update the index to what HEAD is pointing to after the soft step
--hard, which updates the working dir to match the state of the index

The advantages of IDE integrated documentation

Itai Katz — Mon, 21 Feb 2022 14:07:58 +0000

Image source

Integrating documentation inside the IDE is a convenient method for documentation management. I don't know about you, but I avoid context switching at all costs. I just know how fast I can break my focus.

The easiest way for me to document my code is right in my IDE. Here are three advantage:

It reduces context switching. When I'm looking at code and I want to understand something about it, the documentation is right there. I don't need to leave my IDE and search for info.
I see which parts of the code have been already documented while I'm reading and I make a note to come back later and fill in the blanks.
Reviewing annotations when implementing new code or trying to understand a part of the code- it's more straightforward, easier to review, and just intuitive.

Have you tried IDE-integrated documentation?

VS Code vs. WebStorm: A Comparison

Itai Katz — Mon, 07 Feb 2022 14:03:09 +0000

Everyone has a clear IDE preference and lately I've been using both VS Code and WebStorm. Here's why:

VS Code

Free & open-source
It's customizable, multi-language, fast & lightweight
VS Code combines modern editing & debugging with code assistance and navigation

Webstorm

Highly comprehensive and intelligent
Makes running, debugging, and unit testing of Node.js apps easy
Great code refactoring & auto importing

Considerations

WebStorm gives you the majority of the features you'll need whereas with VS Code, you'll end up installing some extensions manually
WebStorm has amazing Git merge tools that provide for great visualizations of the Git diff changes, making merging complex changes a whole lot easier
WebStorm tracks all file changes out of the box & enables the inspection of file histories, directories & rollbacks
VS Code is lightweight, making it ideal for remote development & fast prototyping

Tl;dr VS Code is open-source, fast & lightweight and WebStorm maximizes code inspection and refactoring.

What's your IDE of choice?