Integrated documentation inside the IDE is slowly becoming the most convenient method for documentation management. Perhaps we’re not quite there yet, but IDE integrated documentation is definitely becoming increasingly important when working with any aspect of code documentation.
Developers joke about the “lazy developer” whose goal is to avoid
alt + tab at any cost. Context switching is a major two thumbs down.
So why is IDE integrated documentation a no-brainer for dev teams working on documentation?
The advantages of IDE integrated documentation
There are many dev teams where the requirement for clean code - meaning comment-free self-explanatory code - is very alive and well.
But there comes a time when you need documentation to explain a more complicated flow in your application, and you have to write it down somewhere.
With many open source projects, developers use a Markdown file README.md, with instructions, for example, about how to run the app, how to test your code, etc. But whatever document you’re using, it’s going to be static. If you want to contribute to the project, you don’t know what line of code is related to the line of code you’re reviewing. So you can see it inside your IDE, but it’s not integrated in it.
With integrated documentation in your codebase, you can read and write your documentation in the ideal place where you would want to be writing, reviewing, explaining it to another developer, or changing the documentation itself.
Integrated documentation reduces context switching
So could there actually be an end to the
alt + tab nightmare with IDE integrated documentation?
The fact that code is going to change and constantly needs updating is part of the developer world, and this is also true for code documentation. If every time you need to make an update, you have to switch contexts from your IDE to an external place to write your documentation, it’s a break of your concentration and focus.
One of the main advantages of IDE integrated documentation is that you eliminate the amount of context switching. So if you’re looking at a part of the code, you want to understand it, but the documentation about it is somewhere else, and you have to switch out of the IDE.
This problem is somewhat alleviated when you integrate the documentation in your IDE. You’ve got the code right there. There’s no context switching, and everything is much more intuitive.
You can see which parts of the code have been already documented while you’re reading it
With select platforms that integrate documentation in your IDE, the moment you open your code, you can immediately see whether or not someone has already documented the code or if the code has no documentation and should really be documented at some point.
Reviewing the annotation when implementing code
Another big win with integrated documentation inside your IDE: reviewing annotations when implementing new code or trying to understand a part of the code. Again, it's more straightforward, easier to review, and just intuitive.
How Swimm helps with IDE integrated documentation
So if you’re a developer and you’re working on part of the codebase, and you want to understand what it does without the previous developer sitting right next to you – with Swimm’s plugin, you can see an annotation of a waves icon beside the line number. And then all you have to do is click it and voilà - you open the snippet-related documentation right inside the IDE – and you don’t have to go outside the IDE at all.
In this snippet below, you can see an example of our WebStorm plugin with a project that is using Web Worker. By clicking the blue waves icon, you get to a doc explaining exactly what’s going on.
Below is the Swimm waves icon and annotation of a related Swimm doc using Swimm’s VS Code plugin. This is an example of documentation on the actual Git source code.
Say you have this fork of the repo with Swimm's documentation, and want to add a new command to the API of Git. While browsing the relevant parts of the code, Swimm's plugin will notify you if there's relevant documentation - and you can immediately jump in from the link to the doc.
Context switching never should be slowing dev teams down these days. With integrated documentation in your IDE, it’s an intuitive and smart approach to reviewing and writing documentation.
Code documentation has changed and is no longer out there in left field. Join us at the home plate and check out Swimm's demo to learn more about Swimm. The ball is in your hands.