Hi,
I am not sure is it only me, but to me the QV documentation (starting with the obvious QV Server Reference) looks to be of very poor quaility.
I have recently read a lot of QV document while we were evaluating QV for a reporting solution. I found the documentation difficult to read; it was not very well organized, it did not drive me through the subjects. There are many overlaps; on the other hand, some areas do not seem to be covered (or information is not publicly available).
I was reading a lot of Oracle, Java, Microsoft, W3.org, IEEE and other documentations and thus I have an idea how a good, self-explanatory and complete/consistent documentation should look like. QV documentation is not up to my expectations.
My observation include:
- Inconsistency:
- in code style
- keywords are written in lowercase, UPPERCASE and CamelCase
- inconsistent use of spaces between keywords/keywords and parameters/inside and outside of braces
- in content: keywords differ in syntax definition and in description (e.g. group_by vs. group by, order_by vs. order by)
- in text formatting:
- inconsistent use of bold and italic characters in syntaxt descriptions
- missing syntax definition formattting (e.g. FirstValue() and LastValue())
- in content
- items included in syntax defintion are not described; items described not included in sytax definition (e.g. XMLSAX and XMLSIMPLE)
- Incompleteness:
- missing information items
- format specification items Codepage is, UTF7, OOXML and QVX
- missing description of filters (filter specifiers ) format specification item
- Incorrectness
- wrong syntax defintions
- missing elements (e.g. missing | in syntax definition of Load after from_fieldfield [format-spec])
- unclear defintions (e.g. how to interpret [ where criterion ] | while criterion ] in Load defintion? Choice or both possible but optional?)
- wrong defintions
- e.g. valid value is UTF8 but documentation refers to it as UTF-8.
- Clarity
- Language: some sentences are difficult to understand due to missing punctuation or transliteration from other langauge with different grammar rules (Swedish?); or just plain incorrect spelling. A complete review by a native English-speaking proofreader would be absolutely neccesary.
- An extreme example from QlikView Memory Management and Hardware Guidelines:
“QVS -as menaced earlier- uses all CPU in an intense burst. The virtual machine works as a lair between OS and hardware causing decrees in performance.”
(Speech recognition issues?)
- Structure of QV Reference Manual and QV Server Reference Manual is not helping understanding. The sequence and order of topics is not right; purely reference parts are mixed with tutorial kind of parts.
- Discussing related items in groups would be clearer (e.g. prefixes, join/keep, etc.)
- Syntax diagrams and full BNF of the script langauge would be essential.
- Format
- PDF is not the best format for online reading/studying. HTML and ebook formats would be better.
- A Wiki would be great
I think QV should completely review and rework their documentation and make it _all_ fully available, even for non-customers. It is difficult to make a decision on wether to include QV in the technology stack if most of the information is not available; even if the product itself seems to be OK.
Does anyone have the same impression about QV documentation? Please, let me know in comments/feedbacks.
Regards,
Szilard
.png "Luminary Alumni"){kind=icon}