Qt-contributors-summit-2013-Documentation-Content-and-Structure: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Add "cleanup" tag)
(Simplify punctuation)
Line 3: Line 3:
Proposed topics:
Proposed topics:


-General introduction and “how documentation works”<br /> -Publishing new projects and setting up new module documentation<br /> -Content and usability
-General introduction and "how documentation works"<br /> -Publishing new projects and setting up new module documentation<br /> -Content and usability


Some ideas, wishes, and proposals in the session:
Some ideas, wishes, and proposals in the session:


-Keep <span class="caps">DITA</span> <span class="caps">XML</span> output because Blackberry documentation needs it<br /> -Keep QDoc because of the <span class="caps">QML</span> support and the amount of documentation to convert to be done<br /> -Host .qch files at the doc-snapshot.qt.io site (or elsewhere) for people to download<br /> -Readability and information flow needs to be consistent – Maybe combine pages into one long page? – Edit the use of the landing pages and <span class="caps">API</span> pages and the use of the visible text. (Clicking a link may take you elsewhere) – Maybe have the commit template or CI warn about the use of the 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. “Qt <span class="caps">QML</span>and “QtQml” go to different pages.<br /> -Can we get the doc sanity bot to check the other repositories? – We can host the QDoc warnings online too<br /> -Keep the important information in the reference, not wikis or forums.<br /> -Redirects in qt.io and qt.digia.com needs auditing.
-Keep <span class="caps">DITA</span> <span class="caps">XML</span> output because Blackberry documentation needs it<br /> -Keep QDoc because of the <span class="caps">QML</span> support and the amount of documentation to convert to be done<br /> -Host .qch files at the doc-snapshot.qt.io site (or elsewhere) for people to download<br /> -Readability and information flow needs to be consistent – Maybe combine pages into one long page? – Edit the use of the landing pages and <span class="caps">API</span> pages and the use of the visible text. (Clicking a link may take you elsewhere) – Maybe have the commit template or CI warn about the use of the 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. "Qt <span class="caps">QML</span>" and "QtQml" go to different pages.<br /> -Can we get the doc sanity bot to check the other repositories? – We can host the QDoc warnings online too<br /> -Keep the important information in the reference, not wikis or forums.<br /> -Redirects in qt.io and qt.digia.com needs auditing.

Revision as of 13:25, 23 August 2015

This article may require cleanup to meet the Qt Wiki's quality standards. Reason: Auto-imported from ExpressionEngine.
Please improve this article if you can. Remove the {{cleanup}} tag and add this page to Updated pages list after it's clean.

Proposed topics:

-General introduction and "how documentation works"
-Publishing new projects and setting up new module documentation
-Content and usability

Some ideas, wishes, and proposals 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.io site (or elsewhere) for people to download
-Readability and information flow needs to be consistent – Maybe combine pages into one long page? – Edit the use of the landing pages and API pages and the use of the visible text. (Clicking a link may take you elsewhere) – Maybe have the commit template or CI warn about the use of the 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. "Qt QML" and "QtQml" go to different pages.
-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.
-Redirects in qt.io and qt.digia.com needs auditing.