QtCS2024 Qt Documentation: Difference between revisions
Jump to navigation
Jump to search
Line 17: | Line 17: | ||
=== Feedback === | === 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 | * 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. | * Team is formed by tech writers, and sw engineers. | ||
* There is a gerrit group for documentation reviewers in case changes need it. | * There is a gerrit group for documentation reviewers in case changes need it. | ||
Line 29: | Line 28: | ||
* Qt Docs is adopting the usage of the Diátaxis doc organization approach: https://diataxis.fr/ | * Qt Docs is adopting the usage of the Diátaxis doc organization approach: https://diataxis.fr/ | ||
* Changes in the sidebar from the docs. | * Changes in the sidebar from the docs. | ||
* (Eddy laughed very hard when the quote "We will not need docs anymore, thanks | * (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: | * Suggestions: | ||
** Use your active voice. | |||
** Lots of people asked for more snippets within the codes. | |||
(discussion started) | (discussion started) | ||
* Cristián requested for snippets to live in files rather than inline in qdoc, | * 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. | |||
* Eddy interjected that having files is even better, because we can compile and | * Tukkaa asked that maybe we could request snippets from the users/readers even if they are not the best quality. | ||
* Tukkaa asked that maybe we could request snippets from the users/readers | |||
* Kai: We have a feedback survey in place that is helping with the process | * 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 | * 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. | * Daniel: we could use LLMs to read/evaluate the snippets provided by people. | ||
(ended) | (ended) | ||
* Infra team is mostly Paul and Topi at the moment, plus a few technical | * 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 | * JIRA: QTBUG/Build tools: qdoc and QTWEBSITE/doc.qt.io | ||
* Responsible from the doc builds on COIN, publishing infra, and provisioning | * 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. | |||
* The qdoc warnings have been documented in order to give to users a good | |||
* qdoc is provisioning via the Qt Installer. | * qdoc is provisioning via the Qt Installer. | ||
* Recent development: | * 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) | (discussion started) | ||
Line 71: | Line 61: | ||
* Paul: We don't have that one, and the new commands are based on need. | * Paul: We don't have that one, and the new commands are based on need. | ||
* Tuukka: what's the use case of videos? | * Tuukka: what's the use case of videos? | ||
* Paul & Nick: we have a few qml ones that are very useful. Creating | * 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. | * Emilia: we could provide videos urls in case that's needed. | ||
(ended) | (ended) | ||
* Soon: | * 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 | * We got some external contributions for translations |
Revision as of 13:04, 5 September 2024
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, 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.
Session Owners
Nicholas Bennet, Qt Group Paul Wicking, Qt Group