Skip to content
  • Categories
  • Recent
  • Tags
  • Popular
  • Users
  • Groups
  • Search
  • Get Qt Extensions
  • Unsolved
Collapse
Brand Logo
  1. Home
  2. Behind the Scenes
  3. Qt.io webservices
  4. Feedback on documentation needed! :)
Forum Updated to NodeBB v4.3 + New Features

Feedback on documentation needed! :)

Scheduled Pinned Locked Moved Qt.io webservices
23 Posts 14 Posters 10.1k Views 1 Watching
  • Oldest to Newest
  • Newest to Oldest
  • Most Votes
Reply
  • Reply as topic
Log in to reply
This topic has been deleted. Only users with topic management privileges can see it.
  • M Offline
    M Offline
    miracules
    wrote on last edited by
    #1

    You might know that we are bringing the documentation to devnet these days, and in that process we are looking into making a couple of design changes in the way the that the class documentation is displayed. Traditionally the page is built up by a selection of lists providing shortcuts for all members of the class; this is followed by e detailed description of the class itself, and at last all the members are listed with their complete description. See example: http://doc.qt.nokia.com/4.7-snapshot/qwidget.html

    The problem with this setup, is that we end up with very long pages which you have to scroll up and down forever. We would like to get your opinion on our suggested solution to this.

    So, here is the old way of doing it:

    1. Scroll down to the lists showing all properties, functions etc.
    2. Click on the function you want to read about.
      !http://i.imgur.com/ME8O4.jpg(Click the function)!
    3. The page jumps down to the function clicked.
      !http://i.imgur.com/YCYEP.jpg(The page scrolls down)!

    The suggested way would be like this:

    1. Scroll to the listed members.
      !http://i.imgur.com/omwYA.jpg(Click on the [+])!
    2. Click the [+] next to the function you want to read about and the details will pop down underneeth.
      !http://i.imgur.com/Pl0LV.jpg(Read the documentation)!

    The new way of navigating contains the same number of clicks, but in addition to showing you a complete function signature right away, it also gives you a short explanation on what the function does.

    The real treat is that we reduce the page height with up to 70% which makes it possible to scroll up and down the whold page without draging the mouse over your desk several times. :)

    The styling is not final!! ;) We just want your feedback on the feature, so don't discard it just because you think it is ugly :)

    So, what say you? The old way; or the high way? :)

    [EDIT: fixed link to QWidget docs, Volker]

    1 Reply Last reply
    0
    • A Offline
      A Offline
      andre
      wrote on last edited by
      #2

      Problem with the new way is, that you can not quickly scan the list visually. BTW: there has been usability testing on the docs at the DevDays in 2009. Perhaps you should use that research instead of starting over?

      1 Reply Last reply
      0
      • L Offline
        L Offline
        loladiro
        wrote on last edited by
        #3

        Well, I usually use the search function of my browser to jump to the correct function I need. I think you should include a function to expand/collapse everything on the page and have registered users set their preferences as to whether they want it expanded or collapsed by default.

        1 Reply Last reply
        0
        • EddyE Offline
          EddyE Offline
          Eddy
          wrote on last edited by
          #4

          I like loladiro's suggestion.
          Andre is also right : we need the possibility to have an overview

          Qt Certified Specialist
          www.edalsolutions.be

          1 Reply Last reply
          0
          • S Offline
            S Offline
            steno
            wrote on last edited by
            #5

            I also like loladiro's suggestion....

            1 Reply Last reply
            0
            • T Offline
              T Offline
              tobias.hunger
              wrote on last edited by
              #6

              I never use the docs site to look up things: It is just too clunky. So do whatever you want, as long as you do not mess up the pages in assistant. So please keep Qt Creator and assistant in mind when changing the stylesheets.

              1 Reply Last reply
              0
              • M Offline
                M Offline
                miracules
                wrote on last edited by
                #7

                loladiro: Indeed, that is a very good suggestion. I also discovered a challenge - with the help of one of the other devnet users - that while hidden, it is impossible to find the text while doing a CTRL+F search.
                The solution to the challenge would be to expand all the sections as you press CTRL+F. I will test this next week.

                Tobias: No worries - this version is for devnot only and is not part of the Qt library at all. However, I believer that the doc team would be happy to know about any suggestions on how to make the documentation better :)

                1 Reply Last reply
                0
                • L Offline
                  L Offline
                  loladiro
                  wrote on last edited by
                  #8

                  Sounds good, keep us posted!

                  1 Reply Last reply
                  0
                  • T Offline
                    T Offline
                    thebootroo
                    wrote on last edited by
                    #9

                    i would like the new design but if there is a collapse all / expand all button and a quick search in page.

                    1 Reply Last reply
                    0
                    • T Offline
                      T Offline
                      thebootroo
                      wrote on last edited by
                      #10

                      the other visible advantage of this will be having the general class documentation directely at top of the page instead of having only a small part an a 'read more' link to see the rest....

                      1 Reply Last reply
                      0
                      • A Offline
                        A Offline
                        andre
                        wrote on last edited by
                        #11

                        I do think there are benefits, if the mentioned downsides can be fixed. One suggestion though, would be to remove the short explanation line. This line makes a quick visual scan more difficult. Instead, you could offer this information when hovering the item (make it expand a little at mouse over or as a tooltip-like popup), and of course show it when the item is expanded.

                        Also, I think the expand button should go in front of the item, not behind it. That is where expand buttons normally are (in tree-view like items and for code folding in Creator).

                        1 Reply Last reply
                        0
                        • M Offline
                          M Offline
                          miracules
                          wrote on last edited by
                          #12

                          All: Thanks for the feedback! Many great suggestions. I believe that I can reach a solution that would make all(most) happy :)

                          1 Reply Last reply
                          0
                          • G Offline
                            G Offline
                            giesbert
                            wrote on last edited by
                            #13

                            I personally don't like the inline expansion. I often just scan the functions to check what exists. And if you open one, you have to close it again, otherwise there is too much between 2 functions from the list.
                            And think of people, checking 5 functions, with similar signatures or names, they open all 5 and then want to scan the list again, they would have to open all 5 (which are one under the other) and close all of them again. In the old docs, you jump to one with one click and have all 5 one under the other. And going back to the list is just one click then.

                            Nokia Certified Qt Specialist.
                            Programming Is Like Sex: One mistake and you have to support it for the rest of your life. (Michael Sinz)

                            1 Reply Last reply
                            0
                            • T Offline
                              T Offline
                              thebootroo
                              wrote on last edited by
                              #14

                              i agree with Gerolf above : the button must be placed before the text, to be all time at the same place.

                              1 Reply Last reply
                              0
                              • S Offline
                                S Offline
                                SimonL
                                wrote on last edited by
                                #15

                                would be fine with a expand all for when its needed however if we decided to keep the old style being able to link to the return type and paramater types from the list of methods at the top of the page would be a useful additional feature

                                1 Reply Last reply
                                0
                                • A Offline
                                  A Offline
                                  andre
                                  wrote on last edited by
                                  #16

                                  Would it be a good idea to have the possibility to also show the inherited methods in the overview in a nice way? It is easy to miss methods or signals that have been defined in base classes, and it would be nice if you could augment the current overview with them. Coolest would be if you could that step-by-step. For instance, if you are viewing the docs on QSslSocket, you could expand the docs like this:

                                  QSslSocket specific stuff (default view)

                                  add QTcpSocket specific methods (the ones not reimplemented by QSslSocket)

                                  add QAbstractSocket specific methods (the ones not reimplemented by the above subclasses)

                                  add QIODevice specific methods (the ones not reimplemented by the above subclasses)

                                  finally add QObject methods.

                                  Methods added to the docs from a baseclass, should probably be marked as such with an [Inherited from <ClassName>] kind of label.

                                  1 Reply Last reply
                                  0
                                  • G Offline
                                    G Offline
                                    goetz
                                    wrote on last edited by
                                    #17

                                    A very good idea, Andre! I would appreciate this.

                                    http://www.catb.org/~esr/faqs/smart-questions.html

                                    1 Reply Last reply
                                    0
                                    • M Offline
                                      M Offline
                                      mlong
                                      wrote on last edited by
                                      #18

                                      That's a great idea, Andre. I would be behind that 100%.

                                      Software Engineer
                                      My views and opinions do not necessarily reflect those of anyone -- living or dead, real or fictional -- in this universe or any other similar multiverse node. Void where prohibited. Your mileage may vary. Caveat emptor.

                                      1 Reply Last reply
                                      0
                                      • T Offline
                                        T Offline
                                        thisisbhaskar
                                        wrote on last edited by
                                        #19

                                        like the new way with few suggestions

                                        1. Like others said, expand button goes to the beginning of the line. Generally function names are of various character lengths. If we have expand button at the end, we may need to search for them.
                                        2. Do we need this line explanation for each method. Does it convey any useful information. If we remove it, its almost same as good old layout, and we gave expand buttons added at the beginning of each method / property.
                                        3. We need to have collapse all button readily available somewhere in each page. Otherwise we end up with same problem that we have now.
                                        1 Reply Last reply
                                        0
                                        • T Offline
                                          T Offline
                                          timoph
                                          wrote on last edited by
                                          #20

                                          Seems that links inside the code blocks have some issues and the link url are visible. You can see the issue in for example http://developer.qt.nokia.com/doc/qt-4.7/qdeclarativeimageprovider.html

                                          @<a href="qdeclarativeimageprovider.html">Image</a> { source: "image://myimageprovider/image.png" }@

                                          Otherwise liking the new style docs.

                                          1 Reply Last reply
                                          0

                                          • Login

                                          • Login or register to search.
                                          • First post
                                            Last post
                                          0
                                          • Categories
                                          • Recent
                                          • Tags
                                          • Popular
                                          • Users
                                          • Groups
                                          • Search
                                          • Get Qt Extensions
                                          • Unsolved