User Manual Feedback and Suggestions

In a push to expand and better the Ignition user manual I’m opening this forum topic to gather feedback from Ignition users, veteran and novice alike, on how you feel the user manual can be improved.

I’d like to know what you feel may be currently missing. What are the things that you may be struggling with understanding that you wish were better explained in the documentation? What do you find yourself struggling the most with that you feel isn’t given enough focus and emphasis in the manual?

We want to here from you with any feedback you may have. Any and all suggestions are welcome.

Just writing to suggest that you update your user manual now that you don’t speak anymore about dynamic properties but custom properties in windows?

Thanks.

Ivan

I think I went through and found any references to dynamic properties and replaced them with custom properties. There weren’t many so if you have a something specific that was tripping you up, just let me know.

Images…FPMI/FSQL manual had great images, the new manual has none. I picture is worth 1000 words.

examples, examples, examples…

maybe some better explanation on scripting such as what are the best uses for certain scripts (gateway vs client vs script modules, etc). Most all the help I use for that comes from the forums but at times, it can be difficult to locate what I am looking for… and all the help I get comes from examples!

I suppose the real question is… what does tech support get the most calls on?

1 Like

Examples. Images. I know I am repeating. The more examples and pictures the better.

Wouldn’t be great to have a section Step by step How To’s in Documentation and at this Forum?

Learning the software, I tended to lean more on these forums rather than the manual. I go to the manual first now but I think most of the help for code usage and understanding came from searching the forum for a real world example since sometimes I wasn’t sure if I was even looking at the solution to the right problem.

I think some type of linking of the manual and the forums would be amazing… probably linking the support forum to the manual somehow, or somehow grouping or archiving the posts that will be a helpful example to those looking in the manual.

One concern with screenshots and videos is that they quickly get dated. For the most part the techniques still apply, but sometimes it looks different or options are located in a different place. How do you feel about the tradeoff between “It isn’t quite right” with “a picture is worth 1000 words”? For me it’s like the step by step how-tos for the wrong version of MS Office - sometimes useful due to consistent terminology, other times a waste. What do you think?

1 Like

Ok, here’s some constructive comparisons between the Ignition manual and FactoryPMI manual.

Let’s say I’m creating a new tag in the Designer and I have a question about some setting in the General properties, here’s the difference between using the FactoryPMI manual and the Ignition manual -

FactoryPMI>Designer>User Interface>Major Sections>SQLTags Editor>General Tab

  1. This section shows a screen cap. This is good, I was in the Designer and needed some information about this section, I open up the manual there’s a screen cap of what I was looking at in the Designer. My brain immediately says this is where I will find the information I need.
  2. The sections in the manual (General Properties, OPC Properties, Scan Class) are broken down as they appear in the screen cap and the designer.
  3. The sections are clearly distinguishable from one another.
  4. The Property Names and Functions are clearly distinguishable from one another.
  5. Links to information elsewhere in the manual that isn’t fully defined in this section. i.e. Datatype
  6. Nick picking points - Probably should have left the word ‘Tab’ off this section to be consistent with the naming of the other tabs (Numeric, Metadata, Permissions…). No information about Access Mode.

Ignition>Project Design>SQLTags>Basic Tag Properties>General Properties

  1. There’s no section in the manual for the SQLTags Editor, you have to dig through the manual to find a section that you feel would pertain to whatever it is you need information about in the SQLTags Editor.
  2. No screen cap. Is this the section I’m looking for? I think so, lets see, I see Property Name in the manual, I see Name in the Designer; I see Property Value in the manual, I don’t see that in the Designer; I see Property Quality in the manual, I don’t see that in the Designer. Maybe this isn’t the section I’m looking for, let me keep looking through the manual for something about the SQLTags Editor. Nope, I guess this is the section of the manual I should be in.
  3. Sections are not as well formatted as they are in the FactoryPMI manual. Granted the formatting in the FactoryPMI manual is a bit dated, but the sections are very clear. The bolding and slight increase in text size used in the Ignition manual don’t clearly mark each section well enough. This point is better seen in the next comparison.
  4. No link to more information about Datatype. I can do a search for Datatype and I find there’s a section called Data Types. But wait, it’s listed under Components, is this the same thing as the SQLTags Datatype? When I read this section it doesn’t say anything about SQLTags, so I could keep searching the manual or make the assumption that it’s the same.

One more comparison between the two manuals on the Text Field Input Component

  1. Sections in the FPMI manual are clear, be it a bit dated. Ignition manual only uses bold, a slight increase in text size, and indentation to lay out the sections which actually causes them to all run together.
  2. FPMI manual breaks out the Properties nicely, although there is no description stating these values represent the Scripting name, Data type. Also not all the properties are listed. The Ignition manual lists all the properties and the values used for the scripting name and data type, but again the formatting makes it all appear to just run together.
  3. FPMI manual shows the event types for the component and the scripting names for each of the events, it also has a link to more detailed information about the events. The Ignition manual shows event types, but not the scripting names for the events, and even clicking on the link Component Event Handlers doesn’t get you to more information about these events.
  4. FPMI manual shows some scripting examples, Ignition manual does not.

Ignition can be pretty simple, drag-drop-boom-done, you can also really dig deep down into it. It would be nice if the manual was that way. This is the SQLTags Editor, this is the General Prosperities section, here is an image of it, this is what everything you see on the screen means, here are links to more detailed information.

Suggestions for improvement -
Have sections in the manual that correspond directly to parts of the Designer. Display images of those sections. Don’t use animated images as those found in the FPMI manual. Perhaps look to Oracle’s Java Docs API manual for styling cues on how to lay out the sections of the manual better. Maybe some links to some How-To videos on YouTube.

Pat - great feedback.

For others - Here is the FactoryPMI users manual and the Ignition Users manual that he was referring to.

Thanks for all of the feedback so far guys. It really does help to hear what you think.

We are going to be slowly adding more and more examples to the user manual as well as a section for new users that acts as a sort of quick overview / how to / user manual navigation tool for common tasks within Ignition. It should be a helpful starting point for those first installing and trying to accomplish rudimentary tasks that may at first seem daunting due to a new and unfamiliar environment.

A how-to section with more advanced or more specific topics is also in the works and any ideas for content for this section would be appreciated. We are working on examples for questions that are commonly asked as well as examples that require the use of multiple Ignition and scripting concepts to solve problems. If some of you have specific scripting problems, concepts you don’t quite understand, etc. then I’d like to hear them. Keep in mind that it would be impossible to cover even a fraction of what you can do with Python, and that many questions regarding scripting will still likely be better off being directed to the forums.

Pat -
Thank you for taking the time to be specific and thorough. Regarding some of what you mentioned:

[ul]There will likely be more screenshots included for topics currently in the user manual.
Your concerns about a lack of explanation of certain windows in the designer is noted. I’ll spend some time going through and focusing on the designer UI and see what all is missing and can be improved. I agree that the UI should be well documented.
Pertaining to the formatting: Are you referencing the online user manual you access via the gateway or are you referring to the PDF manual? [/ul]

BigSchottkyD -
Linking to the forum, while a neat idea, isn’t really possible unfortunately.

Pilotek -
How to’s are coming. If you have suggestions of things that tripped you up and think are applicable to a large portion of those using Ignition then feel free to post them.

cbabb -
Better explanations of Gateway and Client scripts can be added. They are touched on in the overview of the event scripts section in the manual, but they could benefit from some further clarifications.

How-To Tip #1:
[Maybe Tip #2 should be the same on the most used/recommended Linux distribution[s] - one already is on the Forum]

I think a lot of beginners who want to evaluate/start the development Ignitinon install it on a windows (these days most likely Windows 7) machine. Many of them maybe do a fresh install of windows. So the first my tip for How-To’s section of manuals and/or forum is:

How to configure Windows 7 for Ignition Gateway, Designer and client (Viewer) machines.

  • If there is/or may be some relation between windows users/passwords and Ignition users/passwords,
  • if there is/or may be some relation between Time zones of windows, Ignition gateway, Designer and client machines (understanding Time zones) and time coming with data from PLCs (or other data sources) - recommendations,
    - how to correctly setup windows firewall for Ignition, Designer and client, IG with PLC communication of various supported types,
  • what additional software must be installed (Java (versions), SQL server, another recommended software) and what should be installed first,
  • what about antivirus known issues (recommendations what to avoid)
  • if you are installing SQL server, if there is a relation between SQL admin/users accounts names/passwords and Ignition users/passwords, if there is some need to create database for Ignition and if yes (or recommended), how should be their name, if there is some need to create dedicated user for Ignition…
  • what about automatic windows updates settings while running IG,
  • what about automatic Java updates while running IG…

When using a Modbus TCP driver the OPC Tag Path has a lot of possible components and the documentation does a good job of describing a lot of these, but I am constantly looking for something that shows me all of the possibilities. I am thinking along the lines of a command line help reference where optional parameters are surrounded by [] and required options are undecorated. For OPC Tag Path on the modbus TCP driver, something like:

{} = optional
[Device] {UnitId.} RegDesignator RegAddress {.BitAddress}

Followed by an explanation of what all of these items are. Since the documentation is all web based, you could even use colors to denote optional & required pieces. This is the only example that springs to mind so it may be an isolated incident.

Also, I think the scripting documentation could be beefed up a bit. The lists of properties available seem incomplete.

The best example I can think of is the current location of a component. I have yet to see a component documentation page that lists the properties x and y. Even the documentation for system.gui.reshapeComponent doesn’t show how to retrieve the current position (or width and height) in the examples. Granted it is not a big leap to try “.x” and “.y”, and the forums do provide this answer, but I am wondering what else is missing? Is there a java base class for all of these components that defines these common properties?

1 Like

The new Tips & Tricks section added to the manual is very nice, I wish that was in there a year and a half ago!

Somehow, I have never seen this topic until now. Not very observant, I guess.

I will also highly suggest more examples on just about everything. Syntax is important, but actually using the function is not always clear by just looking at the syntax. A good example of lots of examples is what Travis did with the IA Labs Scripting Module. The addTag function has several good examples that cover just about anything you would want to do with it.

Another thing that has always been a pain to me is finding all the different examples of expressions or scripts that are already in the help pages. I think it would be much more helpful to have a section on expressions with every example in that section. The same with scripting. Other sections that use expressions or scripting to do something could tell you to reference the example in the expressions or scripting section for that particular thing, or have a copy of the example there also. Many times I know there is an example of what I need to do with an expression or script. I’ve seen it before. But it is not under the expressions or scripting section. And it takes a good bit of time to find it, in many cases.

Another thing that I think would be helpful is to have a section in the forum where users can post tutorials or examples of how to do certain things, one per topic. I have done a couple of short tutorials in other sections of this forum to help others so they don’t have to struggle trying to figure out how to do something themselves, as I did. But those sections have so many new topics added every day that the tutorials soon scroll off the page and are essentially gone forever. If they were in a dedicated section, I would think they would be much easier to locate later on.

Dave, I’m glad you are working on the User Manual. Ignition is a great product, but in my opinion, the user manual is its weakest point. I know I have had to put in several calls to support for something that should have been easy to find in a user manual. I think it would be well worth IA’s time to do a major rewrite of the user manual. It would probably cut down quite a bit on the number of support calls.

Thanks for your suggestions. We’ve actually just hired a new Technical Writer who will be focused first on the user manual, and then on other helpful materials. We definitely recognize the need for improvement!

Regards,

Great news, Colby. Thanks for the update.

[quote=“Colby.Clegg”]Thanks for your suggestions. We’ve actually just hired a new Technical Writer who will be focused first on the user manual, and then on other helpful materials. We definitely recognize the need for improvement!

Regards,[/quote]

Great idea.
Last people to do documentation on software are the ones that developed it.

I was very happy to meet our new Technical Writer as well as the rest of you, John R. R. Rancher (that’s my name for you and “i’m stickin’ to it”! -adam (in case you didn’t figure it out I was “Adam Austin” at the conference.

Adam, it was also a pleasure to meet you and Albert and Toby. And I too enjoyed meeting and talking with Lisa, the new technical writer. She was very willing to listen to everyone, and I made sure I got my two cents worth in with her. :slight_smile: I think she will be a big asset to IA, and provide the one thing that Ignition needs more than anything else, in my opinion.

I hope she lets us know, through this forum, if she needs anything from the users. I’ve already promised to send her some coding examples to enhance the manual in the scripting and expressions sections. I think many of us will agree that you can’t have too many examples. Syntax is required, but a good example can save you a lot of time when you actually write the code.