QtCS2024 Qt Documentation: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
Line 17: Line 17:
=== Feedback ===
=== Feedback ===


* Current state:
* Current state:
    * 100k+ pages of active Qt documentation
** 100k+ pages of active Qt documentation
    * 5 maintained versions, 3 lts, 55 oss modules, 3 commercial modules, 11
** 5 maintained versions, 3 lts, 55 oss modules, 3 commercial modules, 11 tools.
        tools.
* How it's delivered
* How it's delivered
    * online (doc.qt.io), offline (QtC and QtDS)
** online (doc.qt.io), offline (QtC and QtDS)
    * You can also do a docbook generation.
** 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)
    to LLM" was mentioned by Nick, refering to some common misconceptions about
    LLMs :D)
* Suggestions:
* Suggestions:
    * Use your active voice.
** Use your active voice.
    * Lots of people asked for more snippets within the codes.
** 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)
  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.
    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
* 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.
    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.
    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.
    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
  experience while fixing issues.
* qdoc is provisioning via the Qt Installer.
* qdoc is provisioning via the Qt Installer.
* Recent development:
* Recent development:
    * \fn template common overloads
** \fn template common overloads
    * ordering commands for comparison categories
** ordering commands for comparison categories
    * \details
** \details
    * \nativetype
** \nativetype
    * \tm trademark
** \tm trademark
    * preparing for c++20
** preparing for c++20
    * Refactoring
** Refactoring
    * lots of bug fixing.
** 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.
  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.
** QML DOM API: things are evolving so we need to catchup.
    * Performance upgrades: lots of work on speeding up parts of qdoc.
** Performance upgrades: lots of work on speeding up parts of qdoc.
    * C++ language features that are coming with new versions
** 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

Notes