QtCS2024 Qt Documentation

Session Summary

- How do I contribute?

- Where do I find the documentation I need?

- How do I give feedback?

- Infrastructure

- QDoc: Recent development

- QDoc: Future development

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, referring 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.

Nicholas Bennet, Qt Group Paul Wicking, Qt Group