If you spent any time as a developer, you likely had to follow certain guidelines as to documenting your code or had to deal with trying to figure out what someone else’s code does long after they left and often with little to no documentation.
Like undocumented code, pipelines without documentation can be difficult for the next owner to understand, particularly if it’s years after you’ve left the company. I ran across this exact issue when I had to update a pipeline created by a former team member, so why not revisit the different ways in which you can document your pipelines.
Use Clear Pipeline Names
When building your pipeline, it’s easy to just save the pipeline with the default name. When it comes time to share it outside of your development space, it should have a name that clearly indicates what that pipeline is for.
In addition, standardize on a naming convention for pipelines and maintain this convention consistently across all pipelines and resources within your organization. Having an easy way to tell that multiple pipelines are connected without having to open everyone will make it easier should you need to move that pipeline to a different location.
Rename Your Snaps
Change Snap labels to reflect the action being undertaken.
A pipeline with nothing but default labels on Snaps rarely tells anything more than you read data from one place, did something to it, and sent it somewhere else. In particular, indicate what is being filtered out, transformed, or mapped and what Pipeline Execute is calling a pipeline to do.
Here are two versions of the same pipeline. Which one conveys its purpose better?
Change Input and Output View Names
Whenever you are combining data or splitting it out, you can give an indication of what each path is for by changing the view names. In the section above the Router Snap sends data to views SSO or Non-SSO, so if I validate the pipeline, I can easily see if the account I’m looking at is in an org with SSO, without SSO, or in both.\
Add Pipeline Notes
The Pipeline Notes feature enables you to add custom sticky notes to the pipeline. They can be hidden or displayed as needed, and an icon over the feature button lets you know if any notes exist when you open a pipeline.
Use the Pipeline Properties Info Tab
This tends to be one of the least used ways of adding notes to the pipeline, with Pipeline Notes being the preferred method, but I’ve found it particularly useful when building out our pattern catalog. It’s a great way to provide quick requirements, like referencing child pipelines or required file or historical information, like the team it was built for. Also being able to link to outside documentation on how to use the pipeline has proven to be very useful.
Those are the various ways in which you can document your pipelines. Find which ones work best for you.
