Hello all,
Posting this in the development mailing list to get more feedback.
Topics:
-General introduction and "how documentation works"
-Publishing new projects and setting up new module documentation
-Content and usability
-Documentation creation workflow (sensitive to the release schedule and
modules' progress)
Some ideas, wishes, and proposals brought up in the session:
-Keep DITA XML output because Blackberry documentation needs it
-Keep QDoc because of the QML support and the amount of documentation to
convert to be done
-Host .qch files at the doc-snapshot.qt-project.org site (or elsewhere) for
people to download
-Readability and information flow needs to be consistent
- Links in the pages can go to the overview, C++ page, QML page, or
elsewhere, which is confusing.
- Maybe combine pages into one long page?
- Explain the use of the landing pages and API pages and the use of the
visible text. (Clicking a link may take you to unexpected page)
- Maybe have the commit template or CI warn about the use of links
- Jerome: the usage of links is hard to enforce but it is possible to catch
them during the review time.
- The use of module name is not clear to developers or authors. For
example, "Qt QML" and "QtQml" are different pages and developers may not know
the difference. (could be an autolink issue)
-Can we get the doc sanity bot to check the other repositories?
- We can host the QDoc warnings online too
-Keep the important information in the reference, not wikis or forums.
Some links:
Session wiki:
http://qt-project.org/groups/qt-contributors-summit-2013/wiki/Documentation-Content-and-Structure
Documentation wiki:
http://qt-project.org/wiki/Category:Developing_Qt::Documentation
Cheers,
Jerome P.
_______________________________________________
Development mailing list
[email protected]
http://lists.qt-project.org/mailman/listinfo/development
