Back

Engineering

Integrating Swimm and Continuous Documentation Into Your Workflow

Swimm and Continuous Documentation

We really need to be able to visualize the impact of changing around our tooling before we really get excited about something new, and quite understandably so.

When that something is still quite new and has that fresh beta feel to it, it can be a little hard to visualize something that might be disruptive without at least knowing what the edges look like.

You might be saying “Yes, and disruptive seems kinda like what we need if we’re ever going to get caught up” but the reality is, this stuff is pretty simple and loosely coupled. It has to be; while we have more standard development methodologies than our parents and in some cases grandparents had, every team has a unique dynamic.

The thoughts below aren’t by any means exhaustive, but they should convey an idea of what you can expect.

You’ll Need (Something That Resembles) Continuous Integration

If you already have continuous integration in your workflow, the key is that Swimm needs to run verification checks prior to new code being merged, and you need a defined policy on what to do if a merge would render the documentation out-of-date.

Swimm is a tool that implements Continuous Documentation as a methodology. Thinking about how that can have minimal or no impact on your workflow begins with examining what’s necessary (if anything) to move your team towards something that resembles continuous integration. There needs to be a step in the process where the brakes are pushed if something goes wrong and needs to be fixed, and documentation going out of date needs to be treated as something that’s broken and needs fixing.

This can be as simple as using one of our many sample configurations to set up Swimm verifications to run on your existing Git host, or maybe one of the SAAS options might be a perfect fit. How you handle cases where the documentation breaks is completely up to your team, either one of these strategies has worked well for many of our clients:

  1. You block the PR or build until the documentation has been corrected. The majority of standard code churn can be automatically synced, so going back to make sure everything is in fact okay is usually not a burden. With this strategy, your documentation will never be out of date.
  2. You allow the build to go through, or merge the pull request even though the verification checks fail, and you trigger an issue to go back and fix it that must be resolved within a certain length of time. With this strategy, people viewing the documentation will see notices that parts of it might be out-of-date, until it is brought back in sync.

There’s no ‘better’ here. Whatever makes people feel comfortable is absolutely the correct strategy. We want documentation to become something people trust and feel proud of, so that it’s treated as a finishing touch instead of a burden.

You’ll Need Clear And Defined Goals To Base Your Strategy

Don’t think in terms of numbers and percentages right away. Think about some true things that you’d like to say about your documentation if, say, an applicant was asking about it. That’s going to be different for everyone but here are some examples:

  1. The last few people to join the team on-boarded really quickly while working completely remote.
  2. Our documentation always matches the code, or it’s clearly marked as possibly being out of date.
  3. We’ve got the usual doc-comments as well as links to much deeper explanations that you can find and read right in your editor while you’re looking at the code
  4. Everything you’ll need to learn initially has an illustrated tutorial that was written by whoever wrote the code right after they wrote it.
  5. If you find something isn’t documented, we provide great tools for you to document it while you figure it out.

You can probably think of quite a few more, or maybe those examples don’t really represent the goals you want to achieve. All of that is okay, as long as you have them.

Once you can think of some things that you feel are definitely achievable even with a bit of a stretch, it’s time to think about how you want to approach getting stuff written.

You’ll Need To Discuss Everything With Your Team

Even if your only co-worker is extremely furry and sleeps across your feet under your desk, a dialog about what good enough coverage looks like and what the first few steps toward that are going to be is necessary. You also need to talk about when new code should have more comprehensive narratives, and use the conversation as a demarcation point going forward.

As that solves things for new code, which is quite an accomplishment, the focus is naturally going to shift to everything that currently exists. We discourage setting aside entire days or weeks to write code documentation for two very important reasons:

  • It tends to feel onerous and burdensome, and to many people, it feels like it’s happening at the cost of something else. Resentment isn’t a great intrinsic motivator. Save the cooldown cycles for other fun stuff.
  • It tends to not be as good as it could be if written with a fresh understanding of what it does. You don’t accomplish that in rote sprints.

Consider having an agreement that anything taking more than five or so minutes to figure out is an immediate candidate for better documentation and open issues with a SLA to get it created. But, encourage people to spend time creating it once and for all. Use all of the tools and rich media that our Fluid Editor facilitates to produce something you feel excited to show people. Not having to worry about refactoring breaking things again is a pretty strong motivator, in our opinion.

You know your needs better than anyone, and what is or isn’t going to work well with other people on your team.

Small Changes Add Up To Major Results

As people on your team continue seeing value from the documentation they’ve been creating, particularly through our IDE Plugins, momentum builds and pretty soon you’ll find that most new documentation is mainly associated with new code. Even documenting a few common tasks for onboarding can help bring up coverage for ambiguous code that newer folks are likely to encounter.

Again, and in conclusion, it’s all about the intersection of the goals you want to achieve and the value your team can see in achieving them. Swimm’s design and components strive to not impose rigid structure and requirements as long as everyone is on the same page that the end result is really valuable.