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 starting with Swimm’s IDE plugins.
Swimm IDE plugins help engineering teams
When we browse code, we generally expect 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 without context switching.
VS Code and IntelliJ IDE plugins
With Swimm, you can open documentation right inside your IDE with our VS Code and IntelliJ plugins – without having to move to another place to write documentation. Swimm also lets you know if there are any inconsistencies between the doc that you’re reading and the code that it references. This doesn’t even begin to scratch the surface of what you can accomplish when your documentation, your code and your IDE are all in sync.
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.
Bottom line
To get started, check out Swimm and see how Swimm is helping engineering teams get started and move forward deliberately with documentation and knowledge sharing. And if you want to see Swimm up close, sign up for a 1:1 demo here.
