QtCS2024 Qt Documentation: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
 
Line 72: Line 72:
* We got some external contributions for translations
* We got some external contributions for translations
* There is interest from KDE to use qdoc.
* There is interest from KDE to use qdoc.
* Nicholas: KDE currently using doxygen, and there are some things
* 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.
  that don't work well with KDE code, that qdoc might do, because
* 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.
  of the Qt-nature.
* Nicholas: There has been other details that KDE wants to change but it's not too complicated.
  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==
==Session Owners==

Latest revision as of 13:05, 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