Design Systems Documentation Tools

When creating company-wide guidelines for how UX components should look, what sort of tools do you use to keep this documentation up to date and easily accessible?

Our current “standards” are kept in a Word document. There are so many different properties to try and document that this becomes very cumbersome and clunky very quickly, and I know there has to be a better solution out there. Most of our current documentation is for FTV, but we’ve got projects coming up that will be using Ignition, so we’ll be updating/adding to these soon.

I’ve seen tools like Figma and proto.io. It seems like these are designed specifically for Web and Mobile development, but I’m not sure if these tools would be useful in this field as they may be web/mobile specific.

My question is, has anybody adapted these tools for use with Ignition (or SCADA in general), or found similar tools to help keep everything organized?

1 Like

Shameless plug:
We’re working on a color management module that will allow for managing colors and tokens inside of Ignition’s project structure. It’ll allow for editing stored colors (yes, HSL is supported :wink:), creating themes with unique color palettes, and assigning colors to tokens on a per-theme basis. All the data is stored in a version control compatible format, and based on initial results the client-side performance is much better than existing client tag/script module color storage methods.

Hoping to have a public beta available sometime in the next month.

3 Likes

Commenting to get notifications on any updates in this chain.

I was about to post a similar question. My company just started using Ignition, so we’re still very much in the process of establishing our “standards”. I was wondering if anyone had found any good methods of documenting their Vision or Perspective applications. I’m looking to outline the page structure, tag and property bindings, etc. so that any future modifications/maintenance on the application would be quick and simple.

As it stands, I’m just planning on writing up a Word document summarizing the application, and including details like “X tag corresponds to Y device”, “Z tag is calculated by function A” and so on. Was just curious if anyone had a better way.

This was something when I first started with Ignition that I was concerned with - documenting each window and each component in each window etc.

What I’ve found and what I think is more important is defining some general guidelines and coding patterns/GUI patterns.

For instance, any window that requires a dataset to populate it’s components - this should be done in exactly one spot on the root container, based on a parameter with the record ID. Then each component should have it’s won custom property that I call initialValue that reads from the dataset with a fallback default value in the event that there is no record so of the form try({Root Container.ReadData}[0, 'someColumn'], 'myFallBackValue') - and then your components value is bound to this. Knowing that every window is setup the same way (or at least very close to the same way) gives me a lot of knowledge over the structure of the program while knowing very little about each individual component.

Other pattern’s I would heavily recommend -
Put all business logic in scripting modules, never on a GUI component itself.
Treat the GUI as just a means of getting parameters to feed to functions in the scripting module - the less I have to click on each component looking for business logic, and the more I can just look at the codebase, the easier debugging is.
Try to come up with naming conventions for your components. Any component that ends up feeding data to the function called on the submit button of a window should have a _out_ prefix to the name - thats what I use, you don’t have to use it, but it makes finding where a certain value is coming from in a function from the GUI much easier.
Regarding templates in vision - since providing inputs and getting outputs from a template are both in the template parameters part, this is even more useful - properties that have an _in_ prefix I know must be provided to the template and then that the template will give me values in parameters that have an _out_ prefix.

“X tag corresponds to Y device”,

Stuff like this I think is best handled with proper folder structure of your tags. Everything being on the top level, even with documentation, I think would be harder to manage then well named folders and tags being in the appropriate folders. You could document the fact that you have a folder per PLC, or a folder per Machine, or per Line, or per whatever unit of “stuff” makes sense for the system you are making.

“Z tag is calculated by function A”

Stuff like this I don’t think it’s necessary to document tbh. If I need to know how Z Tag is calculated, I’m going to open up designer and look at it directly, I’m not going to trust a potentially out of date document.

Just my two cents. The big point I am trying to make - decide on what conventions you want to use in your project and document those.

3 Likes

My company is looking to do the same thing. We are reviewing options for including system documentation inside of Ignition projects. What is the best method of keeping the system documentation in the vision/perspective project?

I’ll mention this recent addition to Designer in Ignition 8.1.19 as one potentially valuable resource:

Expanded the concept of ‘resource documentation’ to apply to all resources. Right click any resource in the project browse tree to edit the Documentation describing that resource. Named query and report resources had a unique documentation field previously. This documentation will be upgraded to the new style once the resource is opened and saved in the designer.

3 Likes