Engine Works

Under the hood of Alteryx: tips, tricks and how-tos.
Register for the upcoming Live Community Q&A Session - and don't forget to submit your questions for @DeanS regarding the future role of analytics here.
Alteryx Partner

Auto Documentation Tool

 

Say someone built an Alteryx workflow at your company. What does it do exactly? How does it work? Can you trace it step by step?  And just how did they configure these pieces? 

As data analysts and engineers, we take it for granted that we can readily convey our understanding of data flows to other analysts and engineers. As business drivers and decision makers, our business rules, processes, and decision criteria are clear to us and our teams. 

But as business and data teams become ever more integrated to adapt to accelerating business needs, our requirements and processes grow ever more complex.  

As a result, what once was an innocent question born of curiosity grows into an ever more cumbersome task, making you ask, What does this workflow do, exactly?

Enter the world of documentation. Being a data consultant, I frequently see the same theme play out. Users love building Alteryx solutions, but they often face business situations like these:

·        They need to be able to onboard new users and make sure they can support processes developed by existing and off-boarded users

·        They need to assure compliance and audit teams that everything they build is auditable and reproducible

·        They need engineering to work with them to access the data

·        They need to build confidence with engineering teams that they can build and manage their own automated processes

·        Alternatively, they should be able to sketch out tested and verified designs which they can easily hand to engineering teams (who will then manage implementations)

Whatever the specific situation, the users need to be able to quickly build documentation in parallel with developing and iterating on their workflows. 

When we developed an auto-documentation utility for Alteryx workflows originally, we had positive feedback, but there were a few consistent shortcomings inhibiting adoption:

·        It did not support workflows with containers

·        It did not provide an order of tools (the document would not be helpful in rebuilding a workflow)

·        It did not provide enough details about the configurations of various tools to reproduce the workflow

In addition, we saw a recurring need for sketching images of workflows for easy reassembly. Never to be the ones to shy away from a challenge, we took it upon ourselves to rebuild the documentation utility from the ground up to address these needs.

Enter the latest and greatest in workflow auto-documentation, the Auto Documenter version 2. Simply click Run to get a download link.

Check out a sample of the outputs: 


levsol_0-1585076402524.png

 

 

 

  • Read the full documentation here for installation and usage instructions.
    Check out our demo video
  • Find us online
  • Contact us directly for additional feature requests and support 
  • And don’t forget to check out our other public projects on our Gitlab

 

Comments
7 - Meteor

This is a life saver, thanks a ton!!

Take a thousand bows.

Alteryx Certified Partner
Alteryx Certified Partner

This is awesome!

7 - Meteor

This is awesome

Alteryx Partner

Hello Everyone.

 

By popular demand, we are publishing an alternate version which groups workflow sections by containers:

Please find the newest version on our public GitLab: Here 

 

The version Imager_2020_05_19_Container.zip uses container-based rather than join tool based sectioning. It was built using Designer version 2020.1, so older versions of designer may encounter some bugs on opening- you'll likely need to re-save the files contained in the zip with whatever version you are using.

5 - Atom

I get this error when running - is somebody able to shed some light? 

 

indieching_0-1592387093054.png

 

Alteryx Partner

@indieching 

The last line of the error message suggests pip installer returned a non-successful exit status, which means the two required python packages were not able to install.


The most common cause of this is lack of permission for an admin version of Alteryx Designer installation.  To resolve this:

  1. Right click Alteryx Designer icon and select run as administrator.
  2. Browse to the "Image Workflow.yxwz" file in the autodoc directories and open it.
  3. Use the wand icon in Alteryx Designer to run as analytic app.

Now the app should run with admin permissions and will be able to install these two libs in the Alteryx python environment. Once this runs successfully, you should be able to run the app normally (by double clicking the analytic app from the install directory).

 

 

5 - Atom

@levsol  

Thank you - running it as Administrator fixed the issue!

5 - Atom

@levsol

 

I was able to auto generate the workflow document using this tool. I found the image annotations in the auto generated pdf are too cluttered for my workflow. Is there a way to disable or modify tool annotations in the auto documentation tool?

 

Thanks

 

pbeeram_0-1593986542417.png