QtCS2024 Qt Documentation

Session Summary

Qt Documentation State of the Union (Nicholas Bennet)

- How do I contribute?

- Where do I find the documentation I need?

- How do I give feedback?

Documentation Infrastructure (Paul Wicking)

- Infrastructure

- QDoc: Recent development

- QDoc: Future development

Feedback

* Current state:
   * 100k+ pages of active Qt documentation
   * 5 maintained versions, 3 lts, 55 oss modules, 3 commercial modules, 11
       tools.

• How it's delivered

   * online (doc.qt.io), offline (QtC and QtDS)
   * You can also do a docbook generation.

• Team is formed by tech writers, and sw engineers.
• There is a gerrit group for documentation reviewers in case changes need it.
• the team welcome contributions: https://wiki.qt.io/Category:Developing_Qt::Documentation
• Qt Docs is adopting the usage of the Diátaxis doc organization approach: https://diataxis.fr/
• Changes in the sidebar from the docs.
• (Eddy laughed very hard when the quote "We will not need docs anymore, thanks

   to LLM" was mentioned by Nick, refering to some common misconceptions about
   LLMs :D)

• Suggestions:

   * Use your active voice.
   * Lots of people asked for more snippets within the codes.

(discussion started)

• Cristián requested for snippets to live in files rather than inline in qdoc,

 for translating them to Python (for the pyside docs)

• Eddy interjected that having files is even better, because we can compile and

   check the snippets.

• Tukkaa asked that maybe we could request snippets from the users/readers

 even if they are not the best quality.

• Kai: We have a feedback survey in place that is helping with the process
• Paul: We might end up with worthless snippets, or people using LLMs to

   generate them...and we might need to curated them.

• Daniel: we could use LLMs to read/evaluate the snippets provided by people.

(ended)

• Infra team is mostly Paul and Topi at the moment, plus a few technical

   writers.

• JIRA: QTBUG/Build tools: qdoc and QTWEBSITE/doc.qt.io
• Responsible from the doc builds on COIN, publishing infra, and provisioning

   binaries.

• The qdoc warnings have been documented in order to give to users a good

 experience while fixing issues.

• qdoc is provisioning via the Qt Installer.
• Recent development:

   * \fn template common overloads
   * ordering commands for comparison categories
   * \details
   * \nativetype
   * \tm trademark
   * preparing for c++20
   * Refactoring
   * lots of bug fixing.

(discussion started)

• Cristián: is there any list of missing commands or planned ones?
• Paul: We don't have that one, and the new commands are based on need.
• Tuukka: what's the use case of videos?
• Paul & Nick: we have a few qml ones that are very useful. Creating

 videos is a lot of work and some professional could do it.

• Emilia: we could provide videos urls in case that's needed.

(ended)

• Soon:

   * QML DOM API: things are evolving so we need to catchup.
   * Performance upgrades: lots of work on speeding up parts of qdoc.
   * C++ language features that are coming with new versions

• We got some external contributions for translations
• There is interest from KDE to use qdoc.
• Nicholas: KDE currently using doxygen, and there are some things

 that don't work well with KDE code, that qdoc might do, because
 of the Qt-nature.
 QML is not recognized by doxygen.
 Some KDE people requested to have documentation in the headers
 rather than the implementation.

• Paul: Luca was hired some time ago, and did lots of improvements,

 but he moved to another team. There is currently discussion on
 a patch that enabled header-docs, and Doc team is reviewing.

• Nicholas: There has been other details that KDE wants to change

 but it's not too complicated.

Session Owners

Nicholas Bennet, Qt Group Paul Wicking, Qt Group