QV documentation quality issues

Tue, 07 Aug 2012 04:32:09 GMT

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

Re: QV documentation quality issues

Jason_Michaelides — Tue, 07 Aug 2012 06:55:24 GMT

Personally I have generally found that the combination of the F1 help and reference manuals gets me the answers I need. However, it is hard to disagree with any of the points you so eloquently make. Maybe you should put yourself forward to QlikTech for the job of reviewing it. They'd probably listen! Go through your accountant her or maybe send a note to one of the employees on this forum, or even a direct note to Anthony Deighton with the same detail...

Jason

Re: QV documentation quality issues

Jason_Michaelides — Tue, 07 Aug 2012 06:57:45 GMT

*accountant her!? Bloody auto-correct! I meant "account manager"!!

topic Re: QV documentation quality issues in QlikView

QV documentation quality issues

Re: QV documentation quality issues

Re: QV documentation quality issues