WikiHelp

From Qt Wiki
Revision as of 18:08, 14 January 2015 by Maintenance script (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

English Français Deutsch Polski Українська Português Русский Italian Magyar Spanish 한국어 عربي 日本語 简体中文

Working on the wiki

Getting started

  1. 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
  2. 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.
  3. If someone already created a page on that topic, you will see it in the search results.
  4. You can edit all of the contents on most pages. (page WikiSyntax helps with the markup)
  5. If there is no such page you can create one by clicking “Create new page”.
  6. Use spaces or underscores for titles in both articles and categories. — see the related thread on the forum [qt.io] in a forum poll where can vote.
  7. 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 [warpedvisions.org] and practice your skills at Textism.com [textism.com] 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. (Note: it will even be created if you accidentally misspell a category!)

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:

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 [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

Category: How To

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

Category:How To

you can add a

Category:Kannada::How To

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
  • 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” sign) to make code highlighted like this:

Inline code can be tagged like this: ‹code›someCode(here);‹/code› to look like this

someCode(here);

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 or our FAQ

Categories: