[Development] Assistant WebKit/WebEngine support

Wed Jun 26 12:09:24 CEST 2019

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#

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#

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/#

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:
https://bugreports.qt.io/browse/QTBUG-2730
https://bugreports.qt.io/browse/QTBUG-67439
https://bugreports.qt.io/browse/QTBUG-69778
https://bugreports.qt.io/browse/QTBUG-32084
https://bugreports.qt.io/browse/QTBUG-34525
https://bugreports.qt.io/browse/QTBUG-1136
https://bugreports.qt.io/browse/QTBUG-49417

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.

Kavindra.

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>