(Created page with 'Here are some recommendations for content when creating a tutorial for the MeeGo SDK. == Steps == Details for the SDK documentation creation process are described [here] 1. Crea…') |
m (moved SDK Tutorial Content to SDK/Tutorial content) |
||
| (20 intermediate revisions not shown) | |||
| Line 1: | Line 1: | ||
| - | + | == Creating SDK tutorials == | |
| + | This page includes recommendations for the content of MeeGo SDK tutorials, following the [[SDK/Documentation guidelines]]: | ||
| + | # Update an existing documentation bug to note that you are the author/owner. If none exists for your tutorial, [http://bugs.meego.com/enter_bug.cgi?product=Documentation create a new documentation bug]''' | ||
| + | # Create wiki content as described below. To create a new wiki page, simply enter the URL in your browser: http://wiki.meego.com/Tutorial_Name | ||
| + | # Request review, update bug | ||
| + | # Add a link to your wiki page in the appropriate section of the [[SDK/Docs/1.1/Tutorials | MeeGo SDK Tutorials wiki page]]. | ||
| - | == | + | == Content and formatting == |
| - | + | The content of the tutorial is up to you but it should be concise and accurate. In addition, the following components are recommended if applicable: | |
| - | + | * Environment setup | |
| - | + | * Sample code (with good coding style) | |
| - | + | * Screenshots | |
| + | If you are not the expert, be clear to note that. For example: "Here is one way to <perform this feature>. There may be better ways." | ||
| - | == | + | === Links to content outside wiki === |
| - | + | Linking to offsite content is not encouraged. Advertising, spam, or other inappropriate content will be removed and the author banned from further contributions. | |
| - | + | === Formatting === | |
| - | * | + | Wiki standards should be used and look similar to [[SDK/Docs/1.0/Getting started with the MeeGo SDK for Linux | other tutorial pages]]: |
| - | * | + | * Capitalize first letter of the first title word: |
| + | ** Correct: My tutorial about foo | ||
| + | ** Incorrect: My Tutorial About Foo | ||
| + | * Headings should be level 2 (== Heading ==). Sub-headings level 3 (=== Sub-headings ===). | ||
| + | * Code should be in gray boxes (put one space before code lines or use a <nowiki><pre></pre></nowiki> block). | ||
=== Location on wiki === | === Location on wiki === | ||
| + | Links to your new tutorial should be placed in the TOC of one of the [[Developers|developer guides]] after a peer review and only when it is ready for developers to use. | ||
| - | === | + | === Screenshots === |
| - | + | Screenshots are encouraged if helpful. | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
=== Source Code === | === Source Code === | ||
| + | Source code is important whenever possible. | ||
| + | Code snippets should be shown inside boxes like this | ||
| + | When providing source, be aware of the following: | ||
| + | * License. If the source is not original, you must take appropriate attribution according to the source license. | ||
| + | * Style. Code should follow good coding style. | ||
| + | * Review. If possible, have area experts review the tutorial. | ||
| + | * Simplicity. Keep it simple and clear. Only include the minimal code to showcase the feature. | ||
| - | + | ==== Complete, buildable samples ==== | |
| - | + | If your code is large, you may want to create a project in a public git repository. You can also optionally post a tgz or bz2 zipped archive. | |
| - | + | * Qt projects: If the project is Qt, it should be buildable with: | |
| - | + | qmake && make && make install | |
| - | + | * non-Qt projects: If the project is not Qt, it should be buildable with: | |
| - | + | autogen.sh && make && make install | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
Contents |
This page includes recommendations for the content of MeeGo SDK tutorials, following the SDK/Documentation guidelines:
The content of the tutorial is up to you but it should be concise and accurate. In addition, the following components are recommended if applicable:
If you are not the expert, be clear to note that. For example: "Here is one way to <perform this feature>. There may be better ways."
Linking to offsite content is not encouraged. Advertising, spam, or other inappropriate content will be removed and the author banned from further contributions.
Wiki standards should be used and look similar to other tutorial pages:
Links to your new tutorial should be placed in the TOC of one of the developer guides after a peer review and only when it is ready for developers to use.
Screenshots are encouraged if helpful.
Source code is important whenever possible.
Code snippets should be shown inside boxes like this
When providing source, be aware of the following:
If your code is large, you may want to create a project in a public git repository. You can also optionally post a tgz or bz2 zipped archive.
qmake && make && make install
autogen.sh && make && make install