Bring Knowledge To Your Engineers In Time
For documentation to be effective, or even useful, it must first be discoverable. This not only ensures that engineers find the documentation that they need in the same location that they’re likely to need it, but also ensures that the depth and breadth of your knowledge base can be browsed and consumed in a manner that matches individual learning and exploration style.
I’m often asked about the relationship between Swimm documentation and standard code comments from a tactical perspective - I don’t think there’s a better way to explain this than through a functional tour of our IDE plugins. Let’s start with the ordinary - similar to what you might encounter every day:
When we browse code, we generally expect (or, pray for, depending on the circumstances) comments that summarize what a method or function does, what arguments and types of arguments it needs, and what it returns. Often, these kinds of comments are parsed to automatically produce reference documentation. But it often ends there, with the “what” explained, and perhaps a note on who to talk to if you have questions about it.
Swimm documentation excels in bringing the how, why and when to engineers, and our IDE plugins make sure that this information is discoverable exactly when they need it. Just like in the example above, we see everything that we’re used to - but look - there’s a unit named “How The Assimilation State Machine Works” right at the point where you’re reading the code and might have questions:
Clicking on the special link will open the documentation right there, right in your IDE, and will also let you know if there are any inconsistencies between the doc that you’re reading and the code that it references:
Now you might be an expert on assimilation state machines, you might have even served with Seven Of Nine on Voyager, but not everyone can say the same. The point is, it’s there when and if you need it, and it’s always going to be kept up to date through continuous integration checks.
This doesn’t even begin to scratch the surface of what you can accomplish when your documentation, your code and your IDE are all cooperating together. Looking at the Swimm menu within the IDE, we can see what files are associated with Swimm documents:
You could, for instance, have some Swimm docs for your build configuration scripts that help new developers get set up locally, and have those link through an introductory path through the code.
Swimm’s IDE plugins don’t just help solve the problem of folks not finding different types of documents when they need them, they really help show the value of creating it artfully to begin with. And since you don’t need to worry about it quickly becoming obsolete, our plugins help you recruit more of your team to be enthusiastic about raising your documentation standards.