Results 1 to 12 of 12

Thread: Improving the Qt documentation

  1. #1
    Join Date
    Dec 2014
    Posts
    2
    Qt products
    Qt5
    Platforms
    Unix/X11

    Default Improving the Qt documentation

    Unhappy to search a solution like others users and read some pretentious people who define themself as advanced user or experts and who NEVER answer the question and provide a solution.
    I'm unhappy also to see that, like me, many users don't understand the doc from QT and then, can not use this doc for learn or use the QT tools.

    Also, i can see that: ONLY novice has been able to answer this question by an exemple (a little bit heavy and lake of information in the code... but better than "advanced auto proclamed" users has been able to product for help).

    I think for all this prouve from 2010 to now (2015 the next month, QT/Digia can consider that his doc lake of clarity and can not be usuable by someone don't make the QT code. So that in fact, this doc is a datasheet, and not really a doc.
    That's why, QT/Digia could think about this could be better for users/ futurs clients to have a real clear doc (construct by some workers who can clearly write a doc accessible by ALL) inline and take care about some of this kind of self defined "experts/advanced users" who never prouve this kind of to big pretentions and by this way, desserve the image of DIgia.

    So... for this MODEL proxy and setup implementations way of coding, particulary, the doc serve nothing more than make confused more the users (except this kind of auto proclamed experts... who serve nothing more than make you loose your time).
    Lake of informations / documentation on this difficult part of QT greatfull tool.

    why 5 years without have somethinbg more serious about that ? i don't know... Maybe Digia not understand he has to win more to be clear/more accessible for everybody and not only for auto-proclamed experts/advanced users...

    hope this can be understand, it is easy to understand to.

  2. #2
    Join Date
    Jan 2006
    Location
    Warsaw, Poland
    Posts
    33,359
    Thanks
    3
    Thanked 5,015 Times in 4,792 Posts
    Qt products
    Qt3 Qt4 Qt5 Qt/Embedded
    Platforms
    Unix/X11 Windows Android Maemo/MeeGo
    Wiki edits
    10

    Default Re: Improving the Qt documentation

    I don't think it is as bad as you envision it to be, however I agree that Qt docs has seen better days. Since David Boddie left Trolltech/Nokia in early Qt4 days, the quality of the reference manual has started deteriorating.

    If you compare Qt 4.7 (https://qt-project.org/doc/qt-4.7/) and Qt 4.6 (http://doc.qt.digia.com/4.6/) manuals, you will find the latter much better structured. In those days I knew exactly where to find the information I needed to show to someone. But since the docs changed, it hasn't been so good.

    In my opinion the reason for this is three-fold. First my guess is that there is no single person in Qt project responsible for quality of the documentation. Second of all, Qt went into open governance which increased the amount of code contributed by people outside the company currently owning the brand. It is normal that for developers it is more fun writing code than documenting it. The third reason I can see is that recently we have seen an explosion of the number of classes being part of Qt. I think it is simply very difficult to write documentation for such vast amount of classes.

    Having said that I still think Qt has one of the best reference manuals for this sized framework (or any other product) that I have ever seen. And I will continue to consider it the best source of Qt knowlegde one has access to. Nowadays people, especially inexperienced ones, want to have quick results without much effort on their side -- so they prefer tutorials (preferably video ones so that they don't have to read) where they can just copy the code from, paste it to their projects and expect it to work. In my opinion this is usually a bad idea as this locks down your ability to think and create. And if the tutorial is not "that much correct", this leads into other problems. The sad truth is that you should learn by reading and doing, the more you read the manual, the more experienced you get in finding information in it and it becomes quite easy to predict (albeit since Qt 4.7 not as easy as "in the old days") where to find a particular piece of information. The more you look at examples (there are couple hundred of them bundled with Qt itself, most of them well documented) the easier it gets to adapt them to your needs or just spring you in the right direction.

    From what you have written I can see that you feel disappointed being unable to find the information you were looking for. But I feel it is injustice to say that docs serve nothing more than to make people confused. When I started answering questions about Qt back in 2004-ish, I knew nothing about Qt, I couldn't even implement a proper application with it. When I saw a question on the forum, I simply started browsing the reference manual to find the answer to most of the questions. That approach quickly made me become the "lead troll" of the old forum (and now after 8 years of not participating I still have the largest number of posts there). This way my way of learning Qt and it proved very efficient. If I were to repeat that approach now, with the current quality of the docs, I would probably spend a bit more time looking for answers but I am confident the effect would be the same.

    As far as model-view architecture is concerned, this is a quite difficult topic to comprehend in Qt and I've seen many people struggle to understand it, it is not as easy as setting text on a button And as far as model proxies are concerned, this gets even more complex and confusing. So don't be irritated by your failures in this aspect, we've all been there and done that. I'm sure that if you ask appropriate questions, people will give you appropriate answers however be prepared that they will tell you to read the docs as most of valuable information is there.

    As a side note, Qt Quarterly papers were always been very helpful to me, you can still find them online (some of the issues reprinted in our bit-forgotten wiki). There are also a lot of great materials from different Qt Developer Days conferences. I don't know if this particular presentation is available, but the talk from Marius Bugge Monsen on "Advanced Item-Views" was very enlightening to me in the area of model-view architecture in Qt.
    Your biological and technological distinctiveness will be added to our own. Resistance is futile.

    Please ask Qt related questions on the forum and not using private messages or visitor messages.


  3. The following user says thank you to wysota for this useful post:

    d_stranz (17th December 2014)

  4. #3
    Join Date
    Jan 2008
    Location
    Alameda, CA, USA
    Posts
    5,230
    Thanks
    302
    Thanked 864 Times in 851 Posts
    Qt products
    Qt5
    Platforms
    Windows

    Default Re: Improving the Qt documentation

    @wysota: Well said, and I agree. Sometimes a tutorial is invaluable. The docs often don't make clear how or where a method should be used, what are the prerequisites before it can be called, and so forth. So a tutorial that give a basic "how to" on using a particular Qt feature can save a lot of head-bashing. I also think that people don't realize that Qt comes with a huge set of demo and example programs that show how many features of the toolkit are used.

    self defined "experts/advanced users"
    Maybe Jerome doesn't understand that these titles are a feature of the forum, and aren't names that we posters give ourselves. The more you post, the more exalted your title. I didn't give myself the title "Expert", it just became that once I made enough posts.

    I want to see what wysota's title becomes once he passes 50000 posts.

  5. #4
    Join Date
    Oct 2008
    Posts
    10
    Qt products
    Qt3 Qt4 Qt/Embedded
    Platforms
    Unix/X11

    Default Re: Improving the Qt documentation

    Quote Originally Posted by wysota View Post
    I don't think it is as bad as you envision it to be, however I agree that Qt docs has seen better days. Since David Boddie left Trolltech/Nokia in early Qt4 days, the quality of the reference manual has started deteriorating.
    It was nice to read this compliment, but I can't take credit for what was a team effort, and I feel bad for letting things deteriorate after Qt 4.4. Normally, I wouldn't write/rant in a public forum about this, but I think an explanation is in order.

    The run up to the Qt 4.4 release was not an enjoyable time for various reasons. One of those being that the release contained three large new features (QtWebKit, Phonon, XMLPatterns) and a load of other small-to-medium sized ones. Some of these were partially documented to start with but it required a lot of work to even get some modules to a usable state. Phonon, in particular, required changes to qdoc and the full attention of one of the other writers. I also burned a lot of time working on whitepapers; the process of getting them written for Qtopia (remember that?) was very painful. In addition, in February 2008 the public acquisition process of Trolltech by Nokia started, which I wasn't terribly happy about, and this also created a lot of unnecessary distractions.

    When the acquisition was finalized in June 2008 I stepped down as Lead Technical Writer because I didn't really want to go through the process of management training in Nokia. This left a vacant position that didn't get properly filled until around 2010. In the meantime, the focus of the framework shifted to mobile applications and there was a lot of effort wasted on adding support for Symbian and, at the time, Maemo. There were a lot of quick hacks to support examples on those platforms, plus other Nokia-specific frameworks built on top of Qt started to appear and wanted to be able to reuse Qt documentation. After some internal wrangling and negotiation, QML became a favoured technology and started to require a lot of effort to support, and this began to negatively impact the focus of the documentation as upper management started to worry that new users would find references to old-fashioned widgets and C++ distracting.

    Quote Originally Posted by wysota View Post
    If you compare Qt 4.7 (https://qt-project.org/doc/qt-4.7/) and Qt 4.6 (http://doc.qt.digia.com/4.6/) manuals, you will find the latter much better structured. In those days I knew exactly where to find the information I needed to show to someone. But since the docs changed, it hasn't been so good.

    In my opinion the reason for this is three-fold. First my guess is that there is no single person in Qt project responsible for quality of the documentation. Second of all, Qt went into open governance which increased the amount of code contributed by people outside the company currently owning the brand. It is normal that for developers it is more fun writing code than documenting it. The third reason I can see is that recently we have seen an explosion of the number of classes being part of Qt. I think it is simply very difficult to write documentation for such vast amount of classes.
    I think open governance could have helped in some ways. I think that one requirement for new code is that it is documented, so code written outside Trolltech/Nokia/Digia/Qt has a good chance of being documented. In my experience, it is more likely that code written by insiders will sneak in without documentation. It's true that there has been an explosion of new classes and features without much thought as to what will happen to them in the future - once in the framework they need to be developed and supported otherwise they only lead to confusion for new developers and frustration for existing users.

    That the documentation became badly structured in the Qt 4.6/4.7 timeframe is almost completely due to the knee-jerk reaction to supporting Qt Quick as the preferred way of writing applications, and the focus on mobile applications in general. There were also other initiatives related to this that made the situation worse, such as rampant restyling of the documentation to make it look fancier instead of making it simple and readable. This was because the online documentation became seen as something that should be part of the website "experience" and needed to be styled accordingly. As a result, we also got initiatives like documentation that users could comment on - something we had wanted to have for a long time - but it was done in a way that was not integrated with existing routines.

    Quote Originally Posted by wysota View Post
    As a side note, Qt Quarterly papers were always been very helpful to me, you can still find them online (some of the issues reprinted in our bit-forgotten wiki). There are also a lot of great materials from different Qt Developer Days conferences. I don't know if this particular presentation is available, but the talk from Marius Bugge Monsen on "Advanced Item-Views" was very enlightening to me in the area of model-view architecture in Qt.
    It's a shame that Qt Quarterly just fizzled out. When focus shifted from traditional sales efforts to more of an evangelism/partnering approach there just wasn't the push from the sales team to keep it going, nor was there developer/writer time to work on it. It's a shame that, like much of the online material from a few years ago, there hasn't been an effort to maintain a consistent online presence for the articles. You have to hunt down specific issues from different sites and hope that the domains haven't yet expired. There's a similar story when it comes to the wikis and forums on the Qt sites over the years - they either seem to be poorly migrated or just disappear from the net. Really, what should have happened is that sites like Qt Centre should have been given support so that community resources could have remained available for the community in the long term.

    Well, that's at least part of a rant that I've been waiting to have for a while. I hope it explains some things.

  6. #5
    Join Date
    Dec 2009
    Location
    New Orleans, Louisiana
    Posts
    791
    Thanks
    13
    Thanked 153 Times in 150 Posts
    Qt products
    Qt5
    Platforms
    MacOS X

    Default Re: Improving the Qt documentation

    While I don't consider myself a Qt expert, most of what I have learned about Qt has been from the documentation. Most of the replies I make here are based on what I read from the documentation, not some knowledge bestowed upon me at birth, etc.

    There are many well thought out posts here seeking advice, but there are also many posts looking for answers to questions that are clearly explained in the documentation or require some level of programming aptitude to figure things out.

    It would seem that many of the questions are posted by people that have no programming experience at all and don't understand basic priciples of C++. Since Qt is written in C++, this is an insurmountable hurdle for many people posting to these forums.

    Even if the quality of Qt documentation has gone down since Qt 4.4, improved documentation would not be a substitute for having sound C++ fundamentals prior to attempting to program anything using Qt.

    Just my opinion.

  7. #6
    Join Date
    Oct 2008
    Posts
    10
    Qt products
    Qt3 Qt4 Qt/Embedded
    Platforms
    Unix/X11

    Default Re: Improving the Qt documentation

    Regarding Qt Quarterly, most of the issues seem to be available on the Digia site but the last three issues were hosted on the Qt Developer Network which appears to have dropped off the net. Fortunately, they seem to have been saved by the Internet Archive:

  8. #7
    Join Date
    Jan 2006
    Location
    Warsaw, Poland
    Posts
    33,359
    Thanks
    3
    Thanked 5,015 Times in 4,792 Posts
    Qt products
    Qt3 Qt4 Qt5 Qt/Embedded
    Platforms
    Unix/X11 Windows Android Maemo/MeeGo
    Wiki edits
    10

    Default Re: Improving the Qt documentation

    We have a number of articles in our wiki as well but it is currently disabled until I manage to find time to update it.

    David, maybe we could reprint as many of the articles as we can on QtCentre?
    Your biological and technological distinctiveness will be added to our own. Resistance is futile.

    Please ask Qt related questions on the forum and not using private messages or visitor messages.


  9. #8
    Join Date
    Oct 2008
    Posts
    10
    Qt products
    Qt3 Qt4 Qt/Embedded
    Platforms
    Unix/X11

    Default Re: Improving the Qt documentation

    It would be good to take backups of the ones on Digia's site and the ones currently only available at archive.org. Converting them to wiki markup could take a while, though. It would be better than importing them into the wiki at qt.io, I think.

    I have the sources to some articles, too. Many are also licensed under a Creative Commons license, so republishing them shouldn't cause any trouble.
    Last edited by dboddie; 12th May 2015 at 15:37.

  10. #9
    Join Date
    Oct 2008
    Posts
    10
    Qt products
    Qt3 Qt4 Qt/Embedded
    Platforms
    Unix/X11

    Default Re: Improving the Qt documentation

    The issues on the Digia site are now unavailable. You need to get them from the Internet Archive (also in an earlier, less decorative version).
    Last edited by dboddie; 22nd June 2015 at 00:17.

  11. #10
    Join Date
    Oct 2008
    Posts
    10
    Qt products
    Qt3 Qt4 Qt/Embedded
    Platforms
    Unix/X11

    Default Re: Improving the Qt documentation

    And the current site seems to be archived here.

  12. #11
    Join Date
    Aug 2015
    Location
    Santa Clara, CA
    Posts
    10
    Thanks
    7
    Qt products
    Qt5
    Platforms
    Windows

    Default Re: Improving the Qt documentation


  13. #12
    Join Date
    Jan 2017
    Posts
    18
    Qt products
    Qt5
    Platforms
    Windows

    Default Re: Improving the Qt documentation

    Yes, Above archive links working perfectly to learn through it.

Similar Threads

  1. Documentation
    By wookie1 in forum Qt Tools
    Replies: 2
    Last Post: 24th June 2014, 04:31
  2. Qwt 6.0 documentation
    By m15ch4 in forum Qwt
    Replies: 0
    Last Post: 20th February 2011, 16:48
  3. Improving qgraphicsitem_cast
    By Gopala Krishna in forum Qt Programming
    Replies: 1
    Last Post: 17th June 2007, 18:07
  4. Adding Qt's documentation to Xcode documentation browser
    By fabietto in forum Qt Programming
    Replies: 0
    Last Post: 10th June 2007, 16:38
  5. Improving GV performance
    By Gopala Krishna in forum Qt Programming
    Replies: 7
    Last Post: 3rd June 2007, 08:59

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  
Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide.