[Development] Assistant WebKit/WebEngine support

Riitta-Leena Miettinen Riitta-Leena.Miettinen at qt.io
Wed Jun 26 13:24:30 CEST 2019

Hello all,

I think this thread is mixing at least three separate, if related issues:

  1.  What should be used for the help back end in Qt tools (Qt Creator and Qt Assistant)?
  2.  What should the documentation style look like?
  3.  Should the same style be used online and offline?

For 1), I would like to thank Konrad for the extensive list of options we have there. It would be good to put it in a JIRA task, so that it won’t get lost. We already have a task about looking into one of the options here: https://bugreports.qt.io/browse/QTBUG-74796

For 2), the doc team does not usually decide how the documentation style looks and that might be a good thing, because everybody has an opinion and they are all right, because it is an opinion 😊. The style usually comes from a designer and we implement it as well as the HTML generated by QDoc lets us. We‘ve had lot of technical problems caused by the HTML generator that are stopping us from being flashy and modern, even though of course we’d like to.

For 3), we always answered „yes“, because we felt that the use cases for reading documentation on the web or using it within Qt Creator next to the Code editor were different. In the latter case, the white space was minimized, system font was used, and the text size was smaller to save space. Because QDoc separates Content from formatting, it is easily possible to generate documentation for different purposes from the same source if all the authors use QDoc commands consistently. The helps still looked nice, even they were different from the online version, until we had to start depending on QTextBrowser.

Thanks for the bug reports! To save everyone some time, please look around in JIRA for existing bugs first and report all style-related issues as QTBUGS. The styles come from Qt and only issues in the content of the Qt Creator Manual should be reported as a QTCREATORBUG. This is because the fixes will be done in Qt, not Qt Creator. I moved one of them here and reopened it, because after more study it looks like it might have been cause by a CSS change: https://bugreports.qt.io/browse/QTBUG-76705

So, when you report bugs, the more information you can include about what is wrong and when it changed, the more chance you’ll probably have of getting the bug fixed.



Date: Wed, 26 Jun 2019 10:09:24 +0000
From: "Palaraja, Kavindra" <KPalaraja at luxoft.com>
To: "development at qt-project.org" <development at qt-project.org>
Subject: Re: [Development] Assistant WebKit/WebEngine support
Message-ID: <557EE263-E641-464F-B3B2-AC212C7499D9 at luxoft.com>
Content-Type: text/plain; charset="utf-8"

Wow, I had no idea in my 12 years of being a Technical Writer that it's possible to annoy so many developers just by discussing a possibility of having better looking, higher quality documentation :)

On the other hand, as a former Troll who wrote the first version of Creator's manual (back when it was called Greenhouse) I'm actually slightly honored because so many developers are still so attached to how Qt's documentation looks in Creator.

Firstly -- the documentation isn't only used by you (anyone reading this e-mail). There are other people who use it too, like Designers or Technical Writers. A Designer would cringe at this content and we would lose them as a possible customer. There are also Managers and Architects who look at documentation to decide if they want to buy a Qt license.

Every day, a Technical Writer has two options -- fix content or fix the content experience. It's a daily battle. And if your team doesn't have a Content Strategist, an Information Architect, or a Site Designer, then these criteria are things that the Writer has to consider. So every time your Technical Writer spends time fighting to shrink an image, or find out why something doesn't render as expected, you're wasting their time. You might as well let the Technical Writer spend time on the content. That's the key -- as many of you have said -- you want to have the content there.

OK, you don't care how it looks -- I get it. But I care, as do many other people who may not be on this list, because it makes my content look bad. If the content looks better, you can write less. Imagine getting less walls of text to read. Maybe like Visual Studio Code's Release Notes -- there are GIFs here that show you the steps of how to use a feature, instead of writing those lines of "Select X, choose Y, Click Z."

https://code.visualstudio.com/updates/v1_35 -- They actually display this content in their IDE as well.

Seeing is believing. I apologize for not putting in a screenshot earlier. Here you go, here's the ugly table.

<creator-borderless-table.png> vs. https://doc-snapshots.qt.io/qtapplicationmanager/manifest.html#<https://doc-snapshots.qt.io/qtapplicationmanager/manifest.html>

Here's the diagram that can't be scaled without ruining it's clarity. Yes, there are actually users who expect the diagrams to be sharp. If you have one of those newer monitors, the graininess is enough to give you a headache.

<creator-image-scaling.png> vs. https://doc-snapshots.qt.io/neptune3ui/neptune3ui-qt-safe-renderer-integration.html#<https://doc-snapshots.qt.io/neptune3ui/neptune3ui-qt-safe-renderer-integration.html>

Here's another diagram that took a lot of work to create -- because getting Engineers to agree on something is very hard. But it doesn't scale unlike on the docs site.

<creator-image-scaling2.png> vs. https://doc-snapshots.qt.io/qtautomotivesuite/#<https://doc-snapshots.qt.io/qtautomotivesuite/>

Now I really have to say that I'm not happy about having to point out a flaw in my Creator. It was the first IDE I ever documented. But the look and feel of what its displaying is almost the same as it has been from what I remember 10 years ago. And that's not a good thing. We must progress. You would agree too, wouldn’t you? Our screens are better, our hardware is better, we have more cores in that tiny MacBook Pro than there used to be. Progress is painful because it involves change. But it's time to have better content. Otherwise this is how the content will look like for another 10 years ... and any user or prospective user with an eye for design or symmetry, will use another IDE. We will lose customers. Ask that developer friend of yours who can see that 1 pixel misalignment.

If this means using QtWebEngine, then why not? It's there, it's a module written by some of the smartest developers I know. Who knows, maybe this way the QtWebEngine team gets a chance to test their module in a new way. Maybe there's a way to speed it up and improve its performance. We don't know unless we try. By the way, someone else has asked for it before, 4 years ago: https://bugreports.qt.io/browse/QTBUG-55866

I have filed tickets -- they both got closed as a duplicate for https://bugreports.qt.io/browse/QTCREATORBUG-15887 ... which shows that there might not be other "easy" solutions. Or I'm sure the team would have considered it.

Here are some slightly-related tickets that were filed for QTextBrowser to be improved:

If it was easy to fix them, again, I'm sure the team would have patched QTextBrowser.

Anyway, I rest my case. And to all the developers who have to read my content in Creator -- I'm sorry, I tried.


On 25.06.19, 23:23, "Development on behalf of Giuseppe D'Angelo via Development" <development-bounces at qt-project.org on behalf of development at qt-project.org> wrote:

    Il 25/06/19 16:30, Palaraja, Kavindra ha scritto:
    > The idea is to have parity in the sense of 1:1 appearance of how the documentation looks like.
    > Here's a ticket that hasn't gone very far:
    > https://bugreports.qt.io/browse/QTCREATORBUG-15887
    > Can we keep the personal attacks out of this and perhaps stick to the issue? I'm definitely not lying. I don't see any tables being rendered the way tables should be rendered in HTML. Unless I'm losing my eyesight?
    > You could check:https://doc.qt.io/QtApplicationManager/manifest.html  none of that alternating row color or design shows up. As a Technical Writer, I expect the output to look like that. So why doesn't it? I'm not attached to WebEngine, I just want to get the expected output.

    Because the Qt text document classes (*) don't support that kind of styling:

    > https://doc.qt.io/qt-5/richtext-html-subset.html

    They *do* support tables, and I'll grant, they look horrible. And they
    do support background colours for table cells, meaning that a table with
    alternating row colours could in principle be produced, albeit not by
    using fancy CSS nth-odd/even selectors.

    (By the way, I have no idea how the Assistant docs are currently
    generated and styled.)

    Anyhow, let me raise some further questions:

    * Is the whole idea of moving to a web browser driven exclusively by
    these missing features in terms of styling / HTML / JS support, that
    prevent more unification between content offered on the web vs. the one
    integrated in QtHelp?

    ** Have such missing features been identified, in the first place? At
    least the ones we care about w.r.t. Qt's own help.

    ** Have feature requests been filed against QTextDocument? Have their
    costs then been estimated? (Again, in the principle of EYODF)

    ** Have workarounds been discussed?

    ** Was it simply deemed not worth doing such work when we have another
    working solution, "easy" to reach, and that will survive any
    redesign/restyling of the docs that is going to happen every now and then?

    * Is the whole idea part of a bigger plan of further improving QtHelp,
    e.g. make it possible to load external resources through it such as
    videos, community forums, PDFs, you name it? Basically, out of reach for
    any effort at possibly improving QTD.

    The thing is, the arguments _against_ this move are many. If you combine
    them with the ordinary human behaviour where "fear of change" trumps
    "perceived benefits" every single time, you'll get a very agitated audience.

    (*) you're officially a Qt old-school if you remember the codename for them.

    Giuseppe D'Angelo | giuseppe.dangelo at kdab.com | Senior Software Engineer
    KDAB (France) S.A.S., a KDAB Group company
    Tel. France +33 (0)4 90 84 08 53, http://www.kdab.com
    KDAB - The Qt, C++ and OpenGL Experts


This e-mail and any attachment(s) are intended only for the recipient(s) named above and others who have been specifically authorized to receive them. They may contain confidential information. If you are not the intended recipient, please do not read this email or its attachment(s). Furthermore, you are hereby notified that any dissemination, distribution or copying of this e-mail and any attachment(s) is strictly prohibited. If you have received this e-mail in error, please immediately notify the sender by replying to this e-mail and then delete this e-mail and any attachment(s) or copies thereof from your system. Thank you.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: creator-borderless-table.jpg
Type: image/jpeg
Size: 349457 bytes
Desc: creator-borderless-table.jpg
URL: <http://lists.qt-project.org/pipermail/development/attachments/20190626/5e79dabf/attachment.jpg>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: creator-image-scaling.jpg
Type: image/jpeg
Size: 211271 bytes
Desc: creator-image-scaling.jpg
URL: <http://lists.qt-project.org/pipermail/development/attachments/20190626/5e79dabf/attachment-0001.jpg>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: creator-image-scaling2.jpg
Type: image/jpeg
Size: 192003 bytes
Desc: creator-image-scaling2.jpg
URL: <http://lists.qt-project.org/pipermail/development/attachments/20190626/5e79dabf/attachment-0002.jpg>


Subject: Digest Footer

Development mailing list
Development at qt-project.org


End of Development Digest, Vol 93, Issue 118

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20190626/833e81bb/attachment.html>

More information about the Development mailing list