You would use <this> when you want to <do that>

BKBK

The assistant is pretty darn good. There is one additional item I would like to see at the to of each major section. Put this partial sentence near the top and fill in the two sections:
You would use <this> when you want to <do that>.

Christian Ehrlicher

@BKBK said in You would use <this> when you want to <do that>:

You would use <this> when you want to <do that>.

You should use a better explanation what you really want when you want to get a useful answer from us

SGaist

Hi,

Can you be more precise about <this> and <that> ?

ofmrew

@SGaist I believe that what BKBK is saying is that documentation always tells you how something works, but never how to accomplish what you want done. This has historically been a problem with all documentation, not just programming related documentation. The IBM documentation is a prime example.

You want to know how you should do something to get the results you want. I would assume that by <this> BKBK means "what I want done" and <do that> is the approach. For that, we have books and articles. Just my two cents.

BKBK

@ofmrew Thanks for the elaboration. Said in additional words: Write something short that says why this particular class or method was created. Something like:

We created the QDialog because we needed something to <do this>. It is fundamentally different from the QWidget in that it <compare to QWidget>.

There might even be a table of the top level items with two (or maybe more) columns titled:

| If you want to do this | Then use one of these | Because: |

| some activity here | Name something | its cool |

Side Note: The forum auto-edit changes things around so. I edited a table looking thing just above, but upon submit it is changed quite a bit.

That table could start short with just the top level items and expand is as desired. It might be somelthing that users could add to and save the developers much time. I would be more than glad to help here, but I am a complete novice.
However, I would be more than happy to read and offer a novice's perspective.

An example is Microsoft Windows Forms. I took that at face value and posted on MSDN about somelthing that I saw as a form, then was fussed at because Windows Forms is a specific product line. Ok, so I did some searches and never did find something that told me: Use Windows Forms if you want to <do this>. In my not so humble opinion, that should be one of the first statements written about any product. Indeed, before starting any software project it would be a good idea to write: "This is needed because <elaboration>."
Write it short, write it long and detailed, write it in between, just write it.

Christian Ehrlicher

What's wrong with http://doc.qt.io/qt-5/qdialog.html#details ?

BKBK

@Christian-Ehrlicher followed that link, looks good.
I have Qt Assistance on my display and it is better than most. However the page you suggested provides additional information that I did not find within Qt Assistant.

And I do admit that one of my biggest difficulties is in not seeing what is right in front of me. That is rather aggravating and often embarrassing.

Edit: After looking at that page a bit it is quite good. I am still at the stage where I just want to prove to myself that this thing will fundamentally work before I spent a lot of time looking into details. I probably spoke too quickly.
Thanks for your time and patience.

ofmrew

@BKBK From my experience, over fifty years in the field, programmers hate to do documentation. Big companies usually have professional technical writer to write the documentation. They are not application programmers. Over the years I have gained enough experience to read more into the documentation than is stated.

aha_1980

@BKBK said in You would use <this> when you want to <do that>:

However the page you suggested provides additional information that I did not find within Qt Assistant.

I doubt that, as the page is generated from the same sources. At least the assistant integrated in QtCreator shows the same infos.

Regards

Christian Ehrlicher

The assistant does ship exactly the same content as you can find on the website.

ofmrew

@Christian-Ehrlicher One more point and I will shut up. I believe that I might have misconstrued BKBK's underlying question: it was help in design for which he might have been asking. If that is the case I would point him to the literature on object-oriented design and GUI design. Design Patterns by Gamma, et. al. would be a good starting point.

SGaist

That's also why there are examples and demos that should be looked at.

kshegunov

@ofmrew said in You would use <this> when you want to <do that>:

Design Patterns by Gamma, et. al.

This book is pure evil.