New in Compass: Swimm.io app for Continuous Documentation

[#1]

Hello Compass community 👋 It's Dave from the Compass product team. We thought we'd start the week off with a fresh new integration for you to check out, from our friends at Swimm.io.

Swimm is a product that helps engineering teams sync with code by integrating Continuous Documentation into their development workflow. With Swimm, development teams create and maintain code documentation in a way that's incorporated into the normal development workflow. It's all about treating documentation the same way you treat other crucial parts of your development workflow - like tests, or the code itself.

The Swimm integration for Compass allows you to connect Swimm documentation to your corresponding components in Compass. Specifically, you can add a direct link from Compass to your documentation in Swimm and also track your component's documentation status in Compass using the Swimm app for GitHub.

We're excited about Swimm's potential to change how teams collaborate around code documentation. If you're not already using Swimm, this is a great opportunity for you to check it out. It works especially well for teams using GitHub.

Want to learn more about how Swimm can can help your team? @Tom Ahi Dror from the Swimm.io team is right here in our Compass community and is available to answer questions. You can also book a session directly with Tom here:

https://calendly.com/tom-swimm/30-minute-zoom/

[Jimi Wikman]

Swimm looks awesome!

Great match with Compass as well.

Question is if we can have the documentation in Confluence as well so we can connect the code with solution design?

[Tom Ahi Dror]

Thanks for the warm intro, @Dave Parrish _Atlassian_ !

If anyone wants to hear more about Swimm, check out our product page, or jump on a call with me using the link Dave provided.

@Jimi Wikman - Swimm documentation is saved as .md files within the code itself so that it can change along with it. What some of our clients do with design documentation on other platforms is move it to Swimm when the product team is done with it, to couple it with the code that is written according to the design. That way, the design docs remain accurate throughout the development process. 

[Jimi Wikman]

@Tom Ahi DrorI know, and I have seen it in a few projects with other products. This works great when you have small products like apps that are not connected to centralized design and branding strategies, but I have so far seen this in only 2 companies I have worked with and this setup was only for less than 0.5% of their total code base.

The problem that usually occur with decentralized code and design documentation is that they end up in a silo situation, leading to fragmentation of design especially. I don't think code is as problematic as long as the code documentation is based on systems, and I absolutely love that you can connect it directly into the IDE.

In Swimm, can I add links along with the documentation by any chance and in Confluence I should be able to link reference to Swimm regardless, so that should be fine. It would be nice with a macro though so I can expand the Swimm .md directly in Confluence like you can in your IDE.

Either way, I will look into Swimm more because I can think of a dozen clients that probably would be interested in using it, especially in combination with Compass :)

I am going over your videos and documentation and will probably write a blog post or two about it when time permits :)

[Tom Ahi Dror]

@Jimi Wikman - Yes. You can add links to Confluence from Swimm documents, and also as "steps" on Swimm "Playlists". You can also add deep links to Swimm content in Confluence - This can be used when you have a high level document on Confluence, and you want to direct your reader to more thorough explanations that include references and examples from the code itself.

Looking forward to hearing what you thought about Swimm, and how it can work with Compass! Thanks!

[Jimi Wikman]

@Tom Ahi DrorI love it :)

Thanks for clarifying and I can't wait to try this out :)

[Eli Szus]

@Tom Ahi Dror Wondering if you have any plans to integrate with Jira as well. It seems to be pretty straightforward to cobble together a system to associate documents indirectly to Jira issues, but it would be great if it was a more direct integration.

[Tom Ahi Dror]

Thanks for that suggestion @Eli Szus , we actually are thinking about an integration with Jira. Did you have anything specific in mind? 

[Eli Szus]

(Missed your response somehow. So sorry for the delay.)

@Tom Ahi Dror Some thoughts right off the bat... 

1. The same way that Sentry errors can be linked inside of a Jira ticket, would be great to be able to reference an Jira ticket in a Swimm document and vice versa.
2. Would be great to create a Swimm document directly from a Jira ticket.
3. Show the same Swimm checks that are show in a github PR in associated Jira tickets.
3b. And relatedly, whatever docs are referenced in a commit, pr, etc that are associated with a Jira ticket should be visible directly in the Jira ticket.
4. Ability to alert the developer that they have not added any documents when they transition a ticket to certain statuses.

[Tom Ahi Dror]

Hi @Eli Szus and @Jimi Wikman , following up on this - Now that Confluence and Jira have "Smart Links", Swimm documents can be integrated into Confluence documents and into Jira tickets.

More info here:
https://docs.swimm.io/external-integrations/embed-swimm-docs-into-other-platforms/