WikiHelp: Difference between revisions
Jump to navigation
Jump to search
m (→Need help?) |
No edit summary |
||
| Line 1: | Line 1: | ||
'''English''' [[WikiHelpFrench|Français]] [[WikiHelp | '''English''' [[WikiHelpFrench|Français]] [[WikiHelp German|Deutsch]] [[WikiPomoc|Polski]] [[WikiHelp Ukrainian|Українська]] [[WikiHelpPortuguese|Português]] [[WikiHelp Russian|Русский]] [[WikiHelp_Italian|Italian]] [[WikiHelp Hungarian|Magyar]] [[WikiAyuda |Spanish]] [[WikiHelp_Korean|한국어]] [[WikiHelpArabic|عربي]] [[WikiHelpJapanese|日本語]] [[WikiHelpSimplifiedChinese|简体中文]]<br />[toc align_right="yes&quot; depth="3&quot;] | ||
=Working on the wiki= | = Working on the wiki = | ||
==Getting started== | == Getting started == | ||
# If you have some knowledge to share about Qt, then wiki is the place to share it. '''But restrict your articles to Qt related topics''' | # If you have some knowledge to share about Qt, then wiki is the place to share it. '''But restrict your articles to Qt related topics''' | ||
# Please make sure that the page | # Please make sure that the page you're thinking of creating doesn't already exist. Use the search field on the top right of the ''wiki box'' for this purpose. | ||
# If someone already created a page on that topic, you will see it in the search results. | # If someone already created a page on that topic, you will see it in the search results. | ||
# You can edit all of the contents on most pages. (page [[WikiSyntax]] helps with the markup) | # You can edit all of the contents on most pages. (page [[WikiSyntax]] helps with the markup) | ||
# If there is no such page you can create one by clicking | # If there is no such page you can create one by clicking "Create new page&quot;. | ||
# Use spaces or underscores for titles in '''both''' articles and categories. — | # Use spaces or underscores for titles in '''both''' articles and categories. — "see the related thread on the forum&quot;:http://forum.qt.io/viewthread/2262/ in a [[ForumHelp|forum poll]] where can vote. | ||
# | # Don't pollute the history of a page by doing markup tests, use the [[Playground]] instead. | ||
==How to edit a page== | == How to edit a page == | ||
The editor provides you with the most common functions collected in a kitchen sink. That should get you quite somewhere. | The editor provides you with the most common functions collected in a kitchen sink. That should get you quite somewhere. | ||
If you prefer to write wiki code directly you can have a look at "this cheat sheet&quot;:http://warpedvisions.org/projects/textile-cheat-sheet/ and practice your skills "at Textism.com&quot;:http://textism.com/tools/textile/ They provide a tool that turns Textile - the markup language our wikis use - into HTML for preview. | |||
Please, use the preview option to check your edits before you save unless you are 120% sure that you '''never''' make mistakes. | Please, use the preview option to check your edits before you save unless you are 120% sure that you '''never''' make mistakes. | ||
==How to make your pages easy to use== | '''C++ code will be automatically highlighted on wiki pages!''' | ||
== How to make your pages easy to use == | |||
Help fellow developers find the great insights | Help fellow developers find the great insights you're sharing by following a few simple guidelines: | ||
===Write like | === Write like you're coding === | ||
Good wikis, like good code, are easy to scan and maintain. Each article should cover one topic (much like a class). Each paragraph should contribute one aspect to the topic (like a function). If you change thoughts it helps to change paragraphs so you | Good wikis, like good code, are easy to scan and maintain. Each article should cover one topic (much like a class). Each paragraph should contribute one aspect to the topic (like a function). If you change thoughts it helps to change paragraphs so you don't bury great insights where they're hard to find. | ||
===Use headers for scannability=== | === Use headers for scannability === | ||
Long articles are easier to read if you add some informative headers. Please use h1 level for your introduction and then h2 and h3 levels to outline your discussion. (The editor includes buttons for them.) Try to write your headers so they outline what you have to say all by themselves, because you can then … | Long articles are easier to read if you add some informative headers. Please use h1 level for your introduction and then h2 and h3 levels to outline your discussion. (The editor includes buttons for them.) Try to write your headers so they outline what you have to say all by themselves, because you can then … | ||
===Add a table of content=== | === Add a table of content === | ||
When readers find your article, they will scan the first page to figure out if | When readers find your article, they will scan the first page to figure out if it's what they're looking for. If your article is not much longer than one page, all you need to do is write it. If it's much longer than that, use a table of content to show the reader what's to come. Your opening paragraph plus table of content should be all the reader needs to know whether to click down or click away. | ||
All you need to do is add this tag | All you need to do is add this tag "["toc align_right="yes&quot; depth="3&quot;] (remove quotes surround first bracket) and the wiki engine will create the TOC for you. The tag can appear anywhere, but is helps maintainability if it appears at the beginning of your article. | ||
===Add Categories=== | === Add Categories === | ||
Add category tags to insert a link to your article in the appropriate summary pages. By adding your article to existing categories you help readers find your content. | Add category tags to insert a link to your article in the appropriate summary pages. By adding your article to existing categories you help readers find your content. | ||
If you want to create a new category and summary page, just tag your article to a category that does not yet exist. ''' | If you want to create a new category and summary page, just tag your article to a category that does not yet exist. '''<span class="category! a misspell accidentally you if created be even will it Note:"></span>''' | ||
Here are some popular category tags: | Here are some popular category tags: | ||
&#91;&#91;Category:Bugs]]<br />&#91;&#91;Category:Developing_with_Qt::Qt Quick]]<br />&#91;&#91;Category:Developing with Qt::QtMobility]]<br />&#91;&#91;Category:HowTo]]<br />&#91;&#91;Category:LanguageBindings::PySide]]<br />&#91;&#91;Category:Learning]]<br />&#91;&#91;Category:Tools::QtCreator]] | |||
==How to translate a page== | == How to translate a page == | ||
If you translated a wiki page keep in mind that it has to be accessible from existing language versions. This is quite easy by adding or expanding the navigation at the top of the page. The navigation should follow this pattern:<br />'''Language_of_the_page''' Language1 Language2 … side by side with their corresponding links. | If you translated a wiki page keep in mind that it has to be accessible from existing language versions. This is quite easy by adding or expanding the navigation at the top of the page. The navigation should follow this pattern:<br />'''Language_of_the_page''' Language1 Language2 … side by side with their corresponding links. | ||
For example in this page (remove the space between the brackets | For example in this page (remove the space between the brackets "[ [") the following is used:<br /><code>'''English''' [ [WikiHilfe|Deutsch]] [ [WikiPomoc|Polski]]<code> | ||
In most cases you should name your page by adding the language to the end of the original title (assuming the article was originally written in English. For example, the page '''How to Foo''', translated into Italian would be named '''How to Foo Italian'''. | In most cases you should name your page by adding the language to the end of the original title (assuming the article was originally written in English. For example, the page '''How to Foo''', translated into Italian would be named '''How to Foo Italian'''. | ||
===Right-to-Left languages=== | === Right-to-Left languages === | ||
For languages that are right-to-left just add ''' | For languages that are right-to-left just add '''&#91;right_aligned]''' to the top of the page and it will align to the right, including bullets. | ||
===How to categorize a translated page=== | === How to categorize a translated page === | ||
All translated pages should be initially categorized in the same category as the original. ('''How to Foo''' gets a '' | All translated pages should be initially categorized in the same category as the original. ('''How to Foo''' gets a ''<code&gt;Category: How To&lt;/code&gt;'' tag.) By doing this a developer browsing for example the How To category would see an alphabetized list of all translations of the How to Foo article. | ||
After this initial categorization, feel free to add more — this is a collaborative wiki. If you want, for example, a top-level category that captures all articles translated into Kannada, or for the articles categorized in the '' | After this initial categorization, feel free to add more — this is a collaborative wiki. If you want, for example, a top-level category that captures all articles translated into Kannada, or for the articles categorized in the ''<code&gt;Category:How To&lt;/code&gt;'' you can add a ''<code&gt;Category:Kannada::How To&lt;/code&gt;'' tag too, that's probably a great benefit for those looking for such content. | ||
==Collaboration== | == Collaboration == | ||
Wikis are meant for collaborative editing. To make it as easy as possible for everybody please follow some basic rules. | Wikis are meant for collaborative editing. To make it as easy as possible for everybody please follow some basic rules. | ||
* '''Discuss your pages in the | * '''Discuss your pages in the "Wiki forum&quot;:/forums/viewforum/16/''' | ||
* Write in an understandable, informative, but not too formal language. | * Write in an understandable, informative, but not too formal language. | ||
* Structure your pages with subheadings and a healthy amount of paragraphs for easier understanding and better reading. | * Structure your pages with subheadings and a healthy amount of paragraphs for easier understanding and better reading. | ||
* Explain acronyms, at least at first use. | * Explain acronyms, at least at first use. | ||
* Use meaningful but straight to the point page names. | * Use meaningful but straight to the point page names. | ||
* | * Don't mindlessly throw away other people's work. | ||
* Use [[Tagging]] to group pages by topic. | * Use [[Tagging]] to group pages by topic. | ||
==Syntax highlighting== | == Syntax highlighting == | ||
In the toolbar you will find a code tag (an "at&quot; sign) to make code highlighted like this: | |||
</code><br />#include <QtGui&gt;<br />#include "window.h&quot; | |||
int main(int argv, char **args)<br /> {<br /> QApplication app(argv, args); | |||
Window window;<br /> window.show(); | |||
return app.exec&amp;#40;&#41;;<br />}<br /><code> | |||
Inline code can be tagged like this: | Inline code can be tagged like this: &lsaquo;code&amp;rsaquo;someCode(here);&lsaquo;/code&amp;rsaquo; to look like this <code&gt;someCode(here);</code&gt; | ||
Qt classes are of course supported. | Qt classes are of course supported. | ||
==Category pages== | == Category pages == | ||
Whenever you create a new category for your page the wiki software will create a landing page for it. This page is editable just like any other page. Just click on the link displayed on your page and edit away. All pages within the respective category will be displayed on this page. Why not start it with an introduction to the topic? | Whenever you create a new category for your page the wiki software will create a landing page for it. This page is editable just like any other page. Just click on the link displayed on your page and edit away. All pages within the respective category will be displayed on this page. Why not start it with an introduction to the topic? | ||
==Need help? | == Need help? == | ||
Please, take a look at the "help forum&quot;:/forums/viewforum/16/ or our "FAQ (Qt DN FAQ)":/faq | |||
Revision as of 09:31, 24 February 2015
English Français Deutsch Polski Українська Português Русский Italian Magyar Spanish 한국어 عربي 日本語 简体中文
[toc align_right="yes" depth="3"]
Working on the wiki
Getting started
- If you have some knowledge to share about Qt, then wiki is the place to share it. But restrict your articles to Qt related topics
- Please make sure that the page you're thinking of creating doesn't already exist. Use the search field on the top right of the wiki box for this purpose.
- If someone already created a page on that topic, you will see it in the search results.
- You can edit all of the contents on most pages. (page WikiSyntax helps with the markup)
- If there is no such page you can create one by clicking "Create new page".
- Use spaces or underscores for titles in both articles and categories. — "see the related thread on the forum":http://forum.qt.io/viewthread/2262/ in a forum poll where can vote.
- Don't pollute the history of a page by doing markup tests, use the Playground instead.
How to edit a page
The editor provides you with the most common functions collected in a kitchen sink. That should get you quite somewhere.
If you prefer to write wiki code directly you can have a look at "this cheat sheet":http://warpedvisions.org/projects/textile-cheat-sheet/ and practice your skills "at Textism.com":http://textism.com/tools/textile/ They provide a tool that turns Textile - the markup language our wikis use - into HTML for preview.
Please, use the preview option to check your edits before you save unless you are 120% sure that you never make mistakes.
C++ code will be automatically highlighted on wiki pages!
How to make your pages easy to use
Help fellow developers find the great insights you're sharing by following a few simple guidelines:
Write like you're coding
Good wikis, like good code, are easy to scan and maintain. Each article should cover one topic (much like a class). Each paragraph should contribute one aspect to the topic (like a function). If you change thoughts it helps to change paragraphs so you don't bury great insights where they're hard to find.
Use headers for scannability
Long articles are easier to read if you add some informative headers. Please use h1 level for your introduction and then h2 and h3 levels to outline your discussion. (The editor includes buttons for them.) Try to write your headers so they outline what you have to say all by themselves, because you can then …
Add a table of content
When readers find your article, they will scan the first page to figure out if it's what they're looking for. If your article is not much longer than one page, all you need to do is write it. If it's much longer than that, use a table of content to show the reader what's to come. Your opening paragraph plus table of content should be all the reader needs to know whether to click down or click away.
All you need to do is add this tag "["toc align_right="yes" depth="3"] (remove quotes surround first bracket) and the wiki engine will create the TOC for you. The tag can appear anywhere, but is helps maintainability if it appears at the beginning of your article.
Add Categories
Add category tags to insert a link to your article in the appropriate summary pages. By adding your article to existing categories you help readers find your content.
If you want to create a new category and summary page, just tag your article to a category that does not yet exist.
Here are some popular category tags:
[[Category:Bugs]]
[[Category:Developing_with_Qt::Qt Quick]]
[[Category:Developing with Qt::QtMobility]]
[[Category:HowTo]]
[[Category:LanguageBindings::PySide]]
[[Category:Learning]]
[[Category:Tools::QtCreator]]
How to translate a page
If you translated a wiki page keep in mind that it has to be accessible from existing language versions. This is quite easy by adding or expanding the navigation at the top of the page. The navigation should follow this pattern:
Language_of_the_page Language1 Language2 … side by side with their corresponding links.
For example in this page (remove the space between the brackets "[ [") the following is used:
'''English''' [ [WikiHilfe|Deutsch]] [ [WikiPomoc|Polski]]<code>
In most cases you should name your page by adding the language to the end of the original title (assuming the article was originally written in English. For example, the page '''How to Foo''', translated into Italian would be named '''How to Foo Italian'''.
=== Right-to-Left languages ===
For languages that are right-to-left just add '''&#91;right_aligned]''' to the top of the page and it will align to the right, including bullets.
=== How to categorize a translated page ===
All translated pages should be initially categorized in the same category as the original. ('''How to Foo''' gets a ''<code&gt;Category: How To&lt;/code&gt;'' tag.) By doing this a developer browsing for example the How To category would see an alphabetized list of all translations of the How to Foo article.
After this initial categorization, feel free to add more — this is a collaborative wiki. If you want, for example, a top-level category that captures all articles translated into Kannada, or for the articles categorized in the ''<code&gt;Category:How To&lt;/code&gt;'' you can add a ''<code&gt;Category:Kannada::How To&lt;/code&gt;'' tag too, that's probably a great benefit for those looking for such content.
== Collaboration ==
Wikis are meant for collaborative editing. To make it as easy as possible for everybody please follow some basic rules.
* '''Discuss your pages in the "Wiki forum&quot;:/forums/viewforum/16/'''
* Write in an understandable, informative, but not too formal language.
* Structure your pages with subheadings and a healthy amount of paragraphs for easier understanding and better reading.
* Explain acronyms, at least at first use.
* Use meaningful but straight to the point page names.
* Don't mindlessly throw away other people's work.
* Use [[Tagging]] to group pages by topic.
== Syntax highlighting ==
In the toolbar you will find a code tag (an "at&quot; sign) to make code highlighted like this:
#include <QtGui>
#include "window.h"
int main(int argv, char **args)
{
QApplication app(argv, args);
Window window;
window.show();
return app.exec&#40;);
}
Inline code can be tagged like this: ‹code&rsaquo;someCode(here);‹/code&rsaquo; to look like this <code>someCode(here);</code>
Qt classes are of course supported.
Category pages
Whenever you create a new category for your page the wiki software will create a landing page for it. This page is editable just like any other page. Just click on the link displayed on your page and edit away. All pages within the respective category will be displayed on this page. Why not start it with an introduction to the topic?
Need help?
Please, take a look at the "help forum":/forums/viewforum/16/ or our "FAQ (Qt DN FAQ)":/faq