Qt Contributors Summit 2012
| Founder: | Alexandra |
| Members: | 164 |
| Category: | Meta groups |
Discussion Topics
We want want to be even more attractive and inviting come Qt 5.x with our newly improved documentation. Session will discuss upcoming work and issue to get to the goals set for 5.0 Beta, and if time permits, beyond. As the reorganization and change docs are undergoing need to effect everybody to achieve better documentation quality, ideally, wide maintainer participation is desired. However, perhaps for practical reasons, a rep. maintainer per each module or set of modules defined as functionality ‘X’ in attendance suffices. This maintainer will then commit to communicate to his team notes and practices pertaining to docs.
I hope this session will split to hacking sessions to do actual work on issues that could require guidance to boot strap (QDoc fixes, improvements, module docs restructuring etc.)
Technical issues
Making Documentation Modular
- Current status?
- Issues: Build dependency chain, intrusive changes, cross reference lost, Inherited by” broken ?
- Expected % done by 5.0 ?
- Improvements for beyond 5.0
- How maintainers can help? developers? interested documentation contributors?
- Modularization example / study case?
Documentation Build System
- How to KISS beyond modularization?
- Need to properly document build system for sake of next generations and outside contributors to hack; improve and extend.
- Current build system docs: improvements, dummy tests?
QDoc
- Errors in docs due to lack of knowledge of QDoc syntax.
- Missing QDoc syntax compared to Doxygen?
- Replacing of “old” QDoc syntax.
- Manual needs review, bug reporting , triage and fixing – http://doc-snapshot.qt-project.org/qdoc/
- How to engage community (users, maintainers) to help?
Format and Layout
- Modules follow different documentation styles.
- Example structure – description of example comes first now, other improvements for usability? (we should do some hands on review in a hack session).
- Examples need rewrite away from QWidget.
- Implementation hints in Qt Documentation?
“Social” issues (Content and infra.)
- Documentation bugs assignment in JIRA? (‘team’ mailing list, unassigned, community?)
- Doc bug maintenance https://bugreports.qt-project.org/secure/Dashboard.jspa?selectPageId=11521 ; triage and ownership – who takes care? (user community, developers, maintainers ?)
- Doc team spanning Nokia and community contributors:
- How to gather new doc contributors?
- How to engage maintainers , users ?
- Establish a process for documentation review.
- Consolidating recurring questions into recipes ? (example, http://lists.qt-project.org/pipermail/interest/2012-May/002146.html )
- Center of contribution howtos; Wiki content for people interested in contributing to documentation?(Intro ,How to checkout docs, build, change, merge request etc.)
- Establish a place where to read about all changes in doc practices and markup changes, for example to make sure things like http://www.mail-archive.com/development@qt-project.org/msg02347.html and http://www.mail-archive.com/development@qt-project.org/msg02443.html are easily found if someone expects some functionality and see different results.
