Qt 5 Example Clean-up Project: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
No edit summary
Line 1: Line 1:
=Qt 5 Example Clean-up Project=
h1. Qt 5 Example Clean-up Project


We are working on cleaning up the set of examples in Qt. Qt now has ~445 examples, and this is just way more than needed.
We are working on cleaning up the set of examples in Qt. Qt now has ~445 examples, and this is just way more than needed.


==Goal==
== Goal ==


The goal for this clean-up project is to:
The goal for this clean-up project is to:<br />* make it easier for anyone to find a useful example that serves a given purpose.<br />* make the set of examples easier to maintain<br />* make sure we can be proud of all examples


* make it easier for anyone to find a useful example that serves a given purpose.
== What are examples used for ==
* make the set of examples easier to maintain
* make sure we can be proud of all examples


==What are examples used for==
Examples serve different purposes. These can be:<br />* Snippet: What a developer finds useful to look at to find out how do use/understand an API<br />* Example: To show off how a given class, element, or other works<br />* Demo: What you would like to run to show off Qt's capabilities when wanting to convince someone that Qt is the right choice.<br />* Tutorial: A step-by-step how-to with belonging examples that teach how to implement given functionality.<br />* Test: Stand-alone app that is useful to run to test whether a given class/component/.. still works as intended


Examples serve different purposes. These can be:
== Quality criteria for an example ==
 
* Snippet: What a developer finds useful to look at to find out how do use/understand an <span class="caps">API</span>
* Example: To show off how a given class, element, or other works
* Demo: What you would like to run to show off Qt’s capabilities when wanting to convince someone that Qt is the right choice.
* Tutorial: A step-by-step how-to with belonging examples that teach how to implement given functionality.
* Test: Stand-alone app that is useful to run to test whether a given class/component/.. still works as intended
 
==Quality criteria for an example==


* Does it have a meaningful purpose? Or is the feature it demonstrate deprecated or obsolete in Qt 5?
* Does it have a meaningful purpose? Or is the feature it demonstrate deprecated or obsolete in Qt 5?
* Does it follow Qt 5 “best practice” / recommended way of doing things?
* Does it follow Qt 5 &quot;best practice&amp;quot; / recommended way of doing things?
* Are the comments, text strings <span class="caps">README</span>, etc. up to date? E.g., not mentioning Qt4 or Nokia, not unnecessarily widget- or phone-centric.
* Are the comments, text strings README, etc. up to date? E.g., not mentioning Qt4 or Nokia, not unnecessarily widget- or phone-centric.
* Is the example documentation, i.e. the corresponding .qdoc file, if any, up to date?
* Is the example documentation, i.e. the corresponding .qdoc file, if any, up to date?  
* Does the structure follow the example shown in the [[Qt Documentation Structure|documentation structure overview]] ''[qt.io]''?<br /> (See also [[Writing Qt Examples|guidelines on how to write examples and their documentation]] ''[qt.io]''.)
* Does the structure follow the example shown in the &quot;documentation structure overview&amp;quot;:http://wiki.qt.io/Qt_Documentation_Structure?<br />(See also &quot;guidelines on how to write examples and their documentation&amp;quot;:http://wiki.qt.io/Writing_Qt_Examples.)


==How to get there==
== How to get there ==


# For each example: run it, mark it to belong to one or more of the above mentioned categories, and provide comments on how it works, if it looks good or ugly or something in between i.e. would you be proud to show it off. '''Participate''' by going through some of the examples, and add your comments: [http://community.kde.org/Qt5/Documentation/ExampleList List of examples in Qt 5] ''[community.kde.org]''
# For each example: run it, mark it to belong to one or more of the above mentioned categories, and provide comments on how it works, if it looks good or ugly or something in between - i.e. would you be proud to show it off. '''Participate''' by going through some of the examples, and add your comments: &quot;List of examples in Qt 5&amp;quot;:http://community.kde.org/Qt5/Documentation/ExampleList
# Once the above is done, we will hopefully know how to structure the examples better, and also which ones to delete.
# Once the above is done, we will hopefully know how to structure the examples better, and also which ones to delete.
# Make a demo app that is a collection of all the cool demos we have + more
# Make a demo app that is a collection of all the cool demos we have + more
Please help triaging the examples, and add your comment to the [http://community.kde.org/Qt5/Documentation/ExampleList examples list] ''[community.kde.org]''.

Revision as of 11:18, 24 February 2015

h1. Qt 5 Example Clean-up Project

We are working on cleaning up the set of examples in Qt. Qt now has ~445 examples, and this is just way more than needed.

Goal

The goal for this clean-up project is to:
* make it easier for anyone to find a useful example that serves a given purpose.
* make the set of examples easier to maintain
* make sure we can be proud of all examples

What are examples used for

Examples serve different purposes. These can be:
* Snippet: What a developer finds useful to look at to find out how do use/understand an API
* Example: To show off how a given class, element, or other works
* Demo: What you would like to run to show off Qt's capabilities when wanting to convince someone that Qt is the right choice.
* Tutorial: A step-by-step how-to with belonging examples that teach how to implement given functionality.
* Test: Stand-alone app that is useful to run to test whether a given class/component/.. still works as intended

Quality criteria for an example

  • Does it have a meaningful purpose? Or is the feature it demonstrate deprecated or obsolete in Qt 5?
  • Does it follow Qt 5 "best practice&quot; / recommended way of doing things?
  • Are the comments, text strings README, etc. up to date? E.g., not mentioning Qt4 or Nokia, not unnecessarily widget- or phone-centric.
  • Is the example documentation, i.e. the corresponding .qdoc file, if any, up to date?
  • Does the structure follow the example shown in the "documentation structure overview&quot;:http://wiki.qt.io/Qt_Documentation_Structure?
    (See also "guidelines on how to write examples and their documentation&quot;:http://wiki.qt.io/Writing_Qt_Examples.)

How to get there

  1. For each example: run it, mark it to belong to one or more of the above mentioned categories, and provide comments on how it works, if it looks good or ugly or something in between - i.e. would you be proud to show it off. Participate by going through some of the examples, and add your comments: "List of examples in Qt 5&quot;:http://community.kde.org/Qt5/Documentation/ExampleList
  2. Once the above is done, we will hopefully know how to structure the examples better, and also which ones to delete.
  3. Make a demo app that is a collection of all the cool demos we have + more