[Development] Qt CS 2013 Documentation Session

[Pasion Jerome]

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20130716/05cac987/attachment.html>