Documentation Workshop 2019: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Update agenda)
(Add thoughts/suggestions)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=== Location ===
=== Location ===
Oslo, Norway - Qt offices
Oslo, Norway - Qt office, room: Excellence
=== Date and time ===
=== Date and time ===
11-12 March 2019, 10:00-17:00
11-12 March 2019, 10:00-17:00
Line 10: Line 10:


=== Agenda ===
=== Agenda ===
''The agenda is subject to change at short notice, and should be a tool to guide the workshop rather than a restraint.''
{| class="wikitable"
{| class="wikitable"
!Time
!Time
Line 16: Line 17:
|-
|-
|10-11
|10-11
|Introduction, welcome.
|QDoc
Why documentation?
|Publishing Qt documentation
|Publishing Qt documentation
|-
|-
|11-12
|11-12
|QDoc, and why we do that.
|QDoc strikes back
|Partner session
|Docs in Creator vs online
|-
|-
|12-13
|12-13
Line 29: Line 29:
|-
|-
|13-14
|13-14
|Re-thinking examples
|Why documentation
Partner session w/Luxoft
|Examples & tutorials
|Examples & tutorials
|-
|-
|14-15
|14-15
|Usability
|Rethinking examples
(or: Establishing an onboarding vision)
|Qt6: Opportunities
|Qt6: Opportunities
|-
|-
|15-16
|15-16
|Discussion ("brainstorming")
|Usability
|Discussion ("brainstorming")
|Discussion ("brainstorming")
|-
|-
|16-17
|16-17
|Docs in Qt Creator vs online
|Discussion ("brainstorming")
|Action plan
|Action plan
|}
|}
=== Online Help vs. Online Documentation ===
Currently, we use [https://doc-snapshots.qt.io/qt5-dev/qdoc-index.html QDoc] to generate both the [https://doc.qt.io/qt-5/qthelp-framework.html Qt help files] that can be opened in the [https://doc.qt.io/qtcreator/creator-help.html Qt Creator Help mode] and in [https://doc.qt.io/qt-5/assistant-quick-guide.html Qt Assistant] and the documentation sets that are published online at the [https://doc.qt.io/ Qt Documentation] web site. The contents of the documentation sets are the same, regardless of how they are delivered and where they are released. However, the help viewer used in Qt Creator and Qt Assistant has the functionality to display a table of contents, index, bookmarks, and free-text search. These functions are not available online. Online, we use a fixed sidebar TOC and Google search.
Separate sets of templates are currently generated to create the help files and the online documentation. This is done to save space in the help viewer.
==== Requirements ====
Currently, either [https://doc.qt.io/qt-5/qtextbrowser.html QTextBrowser] or [https://doc.qt.io/qt-5/qtwebengine-index.html Qt WebEngine] can be used as the help viewer back end in Qt Creator. '''The basic requirement from the Qt Creator team is that the API reference documentation must be accessible from Qt Creator (when pressing F1) without internet access or Qt WebEngine support.''' This is because of the following issues:
* Performance - Including Qt WebEngine in the Qt Creator packages increases the download size and makes startup slow.
* Security - Network access and web engine introduce security issues. In some application areas, network access is not allowed at all.
In principle, the Qt Creator team does not have a problem with introducing bells and whistles into the online documentation that are not supported offline. If possible, the additional documentation should be accessible through an external link to the online docs.
An additional requirement is that the help should follow Qt Creator theming ([https://bugreports.qt.io/browse/QTBUG-32778 QTBUG-32778]).
==== Wish list ====
* Integrate '''external documentation''' in Qt Creator, similarly to the current Qt reference documentation integration. For example, if you press F1 on <code>std::string (STL)</code> the C++ documentation (standard reference) should open in a browser. Pressing F1 on <code>printf()</code> should open documentation for the C library or a man-page. F1 on <code>Win32APiFunction</code> should point the browser to Microsoft Documentation if it is possible to figure out the URL.


=== Ideas for discussion points ===
=== Ideas for discussion points ===
Line 66: Line 84:
** For example, Hello World, which really explains how to add modules, headers, source files, and other resources.
** For example, Hello World, which really explains how to add modules, headers, source files, and other resources.
** How much of this can/should be covered by Qt Creator's Wizards?
** How much of this can/should be covered by Qt Creator's Wizards?
== External thoughts/suggestions ==
* In the forums, we see newcomers tripping up on the same issues year after year after year:
** Common rookie mistakes:
**# Not realizing that there are multiple kits per Qt version on Windows ([https://forum.qt.io/topic/87608/windows-install-download-size "Why is Qt 35 GB?!"])
**# Not realizing that [https://forum.qt.io/topic/84198/no-valid-kits-found Qt Creator != Qt]
**# Not realizing that [https://forum.qt.io/topic/79532/msvc2015-64bit-compiler-kit-installation-requirements a compiler must be installed separately]
**# Not realizing that [https://forum.qt.io/topic/100463/cannot-find-lgl-while-building-in-qt Linux developers need OpenGL dev libs]
** Ideally, the installer itself should [https://lists.qt-project.org/pipermail/development/2018-April/032468.html guide users down the right path]. As a backup though, good docs would greatly simplify our job in the forums.
** We do have some [https://doc.qt.io/qt-5/gettingstarted.html existing docs], but it doesn't explicitly cover the points above. I took a stab at [https://1drv.ms/w/s!AnaQjhA33g0K0lkIZPVjfsWrcPSI expanding it] but it turned out quite long-winded.
* To avoid excessively verbose docs like the previous point, interactive docs (like https://pages.github.com/ ) could be used to present only the info that's relevant to the particular user.
* What do you think of officially adopting the [https://forum.qt.io/topic/35616/web-browser-extension-for-improved-doc-searches Qt Doc Search] browser extension into the Qt Project and promote it in the Qt website/documentation?
** ''(Disclaimer: This suggestion is posted by the extension's author)''
== External resources ==
https://blog.qt.io/blog/2019/03/01/the-future-of-documentation/

Latest revision as of 00:45, 8 March 2019

Location

Oslo, Norway - Qt office, room: Excellence

Date and time

11-12 March 2019, 10:00-17:00

Description

A two-day workshop about the state of Qt's documentation. The aim is to get a clearer high-level vision for the docs, and establish a few key actions to proceed with to make that vision a part of reality.

Contact the Qt documentation team for further information or to let us know you'll join (yes, you should!).

Agenda

The agenda is subject to change at short notice, and should be a tool to guide the workshop rather than a restraint.

Time Monday Tuesday
10-11 QDoc Publishing Qt documentation
11-12 QDoc strikes back Docs in Creator vs online
12-13 Lunch Lunch
13-14 Why documentation

Partner session w/Luxoft

Examples & tutorials
14-15 Rethinking examples

(or: Establishing an onboarding vision)

Qt6: Opportunities
15-16 Usability Discussion ("brainstorming")
16-17 Discussion ("brainstorming") Action plan

Online Help vs. Online Documentation

Currently, we use QDoc to generate both the Qt help files that can be opened in the Qt Creator Help mode and in Qt Assistant and the documentation sets that are published online at the Qt Documentation web site. The contents of the documentation sets are the same, regardless of how they are delivered and where they are released. However, the help viewer used in Qt Creator and Qt Assistant has the functionality to display a table of contents, index, bookmarks, and free-text search. These functions are not available online. Online, we use a fixed sidebar TOC and Google search.

Separate sets of templates are currently generated to create the help files and the online documentation. This is done to save space in the help viewer.

Requirements

Currently, either QTextBrowser or Qt WebEngine can be used as the help viewer back end in Qt Creator. The basic requirement from the Qt Creator team is that the API reference documentation must be accessible from Qt Creator (when pressing F1) without internet access or Qt WebEngine support. This is because of the following issues:

  • Performance - Including Qt WebEngine in the Qt Creator packages increases the download size and makes startup slow.
  • Security - Network access and web engine introduce security issues. In some application areas, network access is not allowed at all.

In principle, the Qt Creator team does not have a problem with introducing bells and whistles into the online documentation that are not supported offline. If possible, the additional documentation should be accessible through an external link to the online docs.

An additional requirement is that the help should follow Qt Creator theming (QTBUG-32778).

Wish list

  • Integrate external documentation in Qt Creator, similarly to the current Qt reference documentation integration. For example, if you press F1 on
    std::string (STL)
    
    the C++ documentation (standard reference) should open in a browser. Pressing F1 on
    printf()
    
    should open documentation for the C library or a man-page. F1 on
    Win32APiFunction
    
    should point the browser to Microsoft Documentation if it is possible to figure out the URL.

Ideas for discussion points

  • The state of QDoc and its future
    • Current issues
    • Prioritisation
  • How to renew, drop, and create new examples?
  • How to improve the usability of Qt documentation?
    • Usability of online and offline documentation
    • Utilizing Analytics and/or User studies?
  • How to improve the4 look and feel of Qt documentation?
    • The current look and feel is dated, it doesn't look fresh and minimalist like other developer products. Can we redesign the layout?
    • Can we provide developers with diagram templates, to encourage them to include diagrams that match Qt's branding?
  • What do we want to achieve with examples/demos/tutorials? What are the objectives for the user to learn from each example?
    • How do these relate to the certification process we have?
  • How to create examples, tutorials, which explain why something is implemented in a certain way?
  • How to categorize/prioritize examples and tutorials?
  • Qt Creator vs. our own structure within the documentation
  • Learning track(s) for different topics/technologies (certification as a goal?)
  • How to create even better tutorials for first comers?
    • For example, Hello World, which really explains how to add modules, headers, source files, and other resources.
    • How much of this can/should be covered by Qt Creator's Wizards?

External thoughts/suggestions

  • In the forums, we see newcomers tripping up on the same issues year after year after year:
  • To avoid excessively verbose docs like the previous point, interactive docs (like https://pages.github.com/ ) could be used to present only the info that's relevant to the particular user.
  • What do you think of officially adopting the Qt Doc Search browser extension into the Qt Project and promote it in the Qt website/documentation?
    • (Disclaimer: This suggestion is posted by the extension's author)

External resources

https://blog.qt.io/blog/2019/03/01/the-future-of-documentation/