Whether I was trying to learn about a product before using it or trying to configure a product, I ended up reading most of the documentation of several new or somewhat new AVEVA products, including:
I also recently read through the documentation of some older products such as PI DataLink and the PI Connector For UFL, and while their documentation definitely had some issues, there are not nearly as many as there are in the documentation of newer products.
The number of issues that I found and reported in the documentation of the newer products is atrocious, and there were often multiple issues on the same page. This is a waste of my time and AVEVA's time since someone at AVEVA needs to create a work item for each issue, and then the people responsible for the documentation need to fix the issues and mark each work item as being complete. It would be far more efficient for the people responsible for the documentation to read the documentation from start to finish, fix any issues, and repeat (hopefully not too often) until no more obvious issues exist, and then publish the documentation (for the first time) only when it is fairly polished.
Since the process of fixing mistakes after publication is so inefficient, I am willing to bet that AVEVA will fix only the most critical issues. That is, from AVEVA's point of view, "it's OK if we publish a bunch of mistakes because they're not worth fixing after they're published". That is, if a manager at AVEVA wanted to stop the documentation people from "wasting" too much time fixing issues before publication, they just need to make sure to publish the documentation ASAP to ensure that the issues will be an even bigger waste of time to fix later, which guarantees that the issues won't be fixed, which saves AVEVA from having to pay the documentation people for their time to fix the issues. Please prove me wrong and fix all or almost all of the issues that I and others have reported, and please publish far fewer issues in the future.
Some of the types of mistakes that I have found in the documentation of newer AVEVA products include:
Copying a similar page from the documentation of another product and incompletely updating it to suit the current product. This issue is quite pervasive in the documentation of AVEVA Adapters.
Missing links (e.g. in text like "For more information, see Configuration examples.", "Configuration examples" will not have a link, but it should). This issue is very common.
Missing major details or not making them clear enough early enough (e.g. configuring Kerberos delegation for PI Web API, the existence and role of the Client Failover Service in the documentation of AVEVA Adapters, the fact that the Client Failover Service can handle multiple failover pairs, the ports used by the PI System Connector 3)
Forgetting to mention the equivalent steps in WIndows or Linux for AVEVA Adapters (in cases where the steps for only 1 of the 2 operating systems is mentioned)
Not being clear on exactly what permissions are needed by which service account and where and how to set them
Not stating the default value or behaviour of an optional setting
Not taking enough advantage of tables (e.g. not using a table when there should be one, or not using enough columns and instead stuffing many types of information in a "Description" column")
Hard-coded common paths (e.g. "C:\ProgramData" should be "%ProgramData% since the "ProgramData" folder is not guaranteed to be on the C drive, even though, most of the time, it is)
Misplaced modifiers and other wording with ambiguous interpretations. Sometimes, it is not even clear which interpretation is correct.
Switching or not switching between the text font and the code font in the wrong places, resulting in awkward-looking text or bad spacing
Changing formats 1 character too early or too late (characters include spaces)
Spelling mistakes (e.g. "Open ID" is a common one; it should be "OpenID")
Bad punctuation and related spacing (e.g. unmatched parentheses, 2 periods (..), missing a period at the end of a sentence, space before a period that finishes a sentence, missing space between a period that finishes a sentence and the start of the next sentence)
Missing or too many spaces between words, especially if the words use different formatting
I'm not asking for perfection. Everyone is busy, and writing better documentation increases expenses without increasing revenue, which decreases profits. I get it. However, the amount of money that AVEVA saves by cheaping out on the documentation is negligible, and the frustration of all users increases significantly. I still ask for AVEVA to own up to its mistakes, fix the existing ones, and to do significantly better (than a rough/wrong draft) in the future.
