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

From Qt Wiki
Jump to: navigation, search
 
Line 1: Line 1:
 +
Proposed topics:
  
 +
-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:
 +
 +
-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 14:05, 25 February 2015

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.