Help:Contributing to this Wiki

From akaWolf-Wiki
Jump to: navigation, search


Have you used Wikipedia.org before? Symbian's developer wiki documentation is much like Wikipedia - it's created and maintained by the people that use it.

You're welcome simply to use the documentation, but we'd love for you to work with us to extend and improve it. If you want to make a minor fix to a typo, add a sentence to clarify something, or add a whole new article or series of articles, please go ahead! If you don't want to make edits direct to the wiki, we are still grateful for feedback. The Reviewing section explains how you can let us know what we can do better.

File:Contribute to this wiki wordle.png
Wordle created from the text of this article. Licensed from Wordle under Creative Commons BY license.

How to Get Started

You may have edited something on Wikipedia in the past, and if you have, you'll find it's very similiar to work on our wiki. We use the same wiki engine (MediaWiki), so the way you enter text on the page will be familiar. Unlike Wikipedia, we ask that you register with the website and log in before you make changes or leave comments. This is so we can keep track of who is working on the site and acknowledge their contributions.

In addition to registering we also ask that you put some information about yourself on your user page. You can view and edit your user page by clicking on your username which is an automatic link. Usernames appear in red if there is nothing on that user's page. We ask this because the information in the wiki is only valuable to you if you know that you can trust the source (unlike Wikipedia we don't request a reference for every piece of information). The Symbian community is already very large and is growing very rapidly. Please don't assume that your readers know who you are.

Get help

If you haven't used a wiki before, it's quite straightforward. We've provided a set of help pages to get you started. The best way to find your feet with a wiki is to find a page you like, open it for edit and study how the author has formatted it. To do this, log in and select the edit tab for your chosen page - this will show the page formatting.

Use the edit tab to edit the page Help:Editing

Play around

If you want to play around for a while, you could copy the article into a sandbox page. You can do anything on that page and it'll simply be deleted after a few days, so you don't have to worry about leaving it in a mess.

When you're confident, maybe move on to a page that you think needs some minor adjustments, open that for edit and make your improvements. You can view the text selecting Show preview without committing your changes. Once you're happy with the edits, you must save them by selecting Save page. Don't navigate away from the page until you've saved your edits or you will lose them!

Wiki markup

If you need a reminder of the basic markup, take a look at the Wikipedia cheatsheet.

WYSIWYG

Some people prefer to use a WYSIWYG editing to control the layout of their wiki content. At present no WYSIWYG editor is provided: this is being addressed here: 4787:Decent WYSIWYW needed

Adding an Article

To make it a little easier to start writing an article, we have created some skeleton pages that can be used to structure the layout and help you decide what to include. You can find these in the Skeleton category. Just copy and paste them into a blank page to get started.

The skeletons are split into different types, and further information about each is available here.

We also have a Document Creation Workflow which describes the process of creating a new document. It's intended to help you as a writer and as a reader by defining states for documents which indicate whether they are under construction, incomplete and awaiting further contributions, awaiting review or peer reviewed.

What Shall I Write About?

Write what you want!

  • It's worth checking what we already have on the wiki, by searching, checking through the categories list or simply browsing.
  • One way to find out what is wanted is to look at the page of stubs, which are pages that are wanted but currently incomplete.
  • Another way to find out what is missing is to look at the Wanted Pages list, which is a list of pages that are linked to but don't appear to exist. More information about how to work with the wanted pages list is here.
  • We've also created a set of 'use cases' that describe common Symbian programming tasks. You can find these use cases on the front page of the wiki.

Some of the pages that those use cases link to are not yet complete (the links that are coloured in red). If you spot a red link in a document, or you see a stub message in the text, and you think you can fill out the page, just go ahead!

Migrating an Article

If there's an article on another website that you think would be good to have on this wiki, why not move it over?

All the information in this topic applies equally well to migrating topics; we also have some migration-specific advice here: Help:Migrating Articles. We're also listing what we've transferred here.

Reviewing an Article

An obvious issue with community generated documentation is quality assurance. Symbian expertise and knowledge are spread throughout the community. By peer reviewing articles, especially new articles, in your sphere of knowledge or technology domain you can help us maintain the quality, reliability and authority of our documents. You can see which articles are awaiting review here.

File:Note.pngNote: We'd really like you to say who you are whenever you contribute to the Wiki, but as a peer reviewer this is particularly important.
Please use your User page to describe your role and your position, and something of your background and expertise.

What Else Can I Do?

There are lots of ways you can help us. Contributing doesn't just mean writing a long document about some specialist development topic. See Help:Gardening the Wiki for some ideas. In addition, you can simply help as follows:

Grammar and Punctuation

Are you a pedant who howls at a grocer's apostrophe and groans at a the 'five items or less' queue in your supermarket? Relieve your tension by editing a page or two, and help us get our commas in all the right places.

However, if you don't care too much about punctuation or don't feel confident about your grammar, that's OK too. We hope you'll write anyway. If you're really worried about the standard of your writing let us know if you want us to check your text by putting
{{Copyedit}}
on your page.

Diagrams

Sometimes a graphic or a table explains far better than a block of text ever can. If you think you can add a visual to an article, please do so.

We recommend using the Dia tool for your UML diagrams and flowcharts, as discussed here: Help:Diagrams.

Glossary of Terms

Have you spotted a TLA or a technical phrase that nobody has explained? Do you know what it means? If you do, or if you go to the effort to find out, please consider adding it to the glossary.

Graphics and Illustrations

You might want to use any of the Symbian brand illustrations found here to help guide the reader

Recommended Style

We have a style guide and general Symbian lexicon, for the language and layout we prefer to use, though we don't expect you to know it off by heart. If you can follow some of our guidelines it keeps our text consistent and that makes the text more readable for others. However, we're not going to deduct points if you don't use our exact style, so just go ahead and write in a way that you think communicates.

Heading Levels

Always use Heading level 2 and greater (e.g. == Heading Name == ) as Heading Level 1 renders the same size as the topic title.

Code Formatting

You can find a guide to formatting code in our Help guide.

Search Engine Optimization

We have a short guide to dos and don'ts of writing wiki articles to optimize them for search engines.

Have an Introductory Sentence before your First Heading

Have a sentence describing the purpose of the article and intended audience before your first heading. This is displayed above the table of contents, and gives your user an immediate flavour of what the topic is about and who it is for.

Attribute Authorship

Your authorship and changes to a wiki page are recorded in the page's history tab.

Note that there while there are many authors to a wiki document, you may choose to attribute original authorship explicitly (particularly if you're migrating a document). In this case, state the original author in the first line - linking to the user page if one exists): e.g: ''Original Author:'' [[User:Hamishwillee|Hamish Willee]] gives:
Original Author: Hamish Willee

Using In-line References

We prefer that references are declared in line because it makes it easier for the reader. For example, use "See Games on Symbian OS: A Handbook for Mobile Development" is preferable to "See reference [1]".

In the rare case in which you do not have a URL you can create a proper references list by wrapping the reference in <ref> </ref> tags at the point where you want the link to appear, and putting <references /> where you want the list of references to appear.

Avoid Footnotes

Footnotes should be avoided. Instead, consider:

  • Putting the text into brackets alongside the text
  • Making the footnotes as notes or tips, using the Template:Note and Template:Tip respectively.

If you're not using numbered references, you can also use the <ref> </ref> functionality for footnotes, as described in #Use In-line References above.

Use the Global Glossary

Add new terms to the global Glossary (remembering to add an anchor next to the term). Then link first occurrence of the word in your document to the global glossary - [[Glossary#Term|Term]].

Give Topics and File Uploads a Descriptive Name

The name of all topics and files should be descriptive enough for a user to be able to guess at its origin or purpose. Calling a topic "Discussion", a code example "Example.zip" and an image "Figure1.jpg" are all examples of bad practice.

Make Code Examples More Accessible

If your article has an associated buildable code example, please give it a descriptive name.

At present, you cannot upload zip files to the wiki (although we are working to change that). For now, if you want to make a code example available for download on the wiki, please zip it up and send it to us it (docs @ symbian.org) with a link to both the original and migrated article. We will then upload the code for you and update the zip upload summary appropriately. We are also planning on setting up a Mercurial repository for code examples that are ongoing development projects - you may prefer to use SCM to distribute your example code and work on it collaboratively.

If you create an article to explain what the code does, in the article we recommend that you use the Comes with Code and Compatibility header (as here: Skeleton Code Example Release Notes Topic). These contain links to your file upload and the devices and SDKs you've tested the code on.

Link back to this site if possible

Please link to topics on this wiki in preference to external sites. See the following sections for information on appropriate link destinations.

Links to Forum Nokia and SDN

Forum Nokia and SDN hosted documents may already have been migrated to the Symbian Foundation Wiki so search on some key topics to get links. If the topic has not been migrated and you think its very relevant, add it to the Requested Items section of the Technical Communications Work in Progress page so that it gets prioritised. Otherwise leave the link as is and we can find it using Special:LinkSearch.

Links to Symbian Developer Library

Links to the Symbian Developer Library point to API reference if at all possible, and to API guide if no link exists in the reference.

Link to Books

Almost all references to Symbian Press Books can link to the appropriate anchor in Symbian Press Books.

Feedback

Are you finding the wiki useful? Got a comment on something you've read? Is something wrong, misleading or missing?

If you simply want to change something on this wiki you can usually make a direct contribution by editing the text. If you really don’t have time to make an edit, or think it's a significant issue and needs our attention, you can point out a problem using the comments link found at the bottom of the page. Any comments you make will be published at the bottom of the page for everyone to read.

File:Note.pngNote: You need to be logged into the site to leave a comment, and at present you cannot comment on Help pages (so you won't see a comment link at the bottom of this page). You do not need to be logged in to read comments.

Responses

If you make a comment to a page and want to be keep informed of responses, you can do so by using the Watch tab at the top of the page. Make sure you have updated your wiki preferences to send you an email (if that's what you want) or simply monitor your watchlist. Both of these are found in the Profile box on the left hand side of every wiki page.

If you want to keep track of every comment posted on the wiki, the best way to do this is to go to the SpecialPages:RecentChanges page and use the dropdown menu to look just at the Talk namespace. Or use the Help:Handy RSS Feeds page and drop an RSS feed into your preferred reader.

Moderation

Only the wiki admin team have write access to the comments so if you're offended by a comment, please leave a response to indicate that you think it needs moderating. We'll pick up your remark in our queue and act on it.

Formatting

The comments box should accept standard wiki markup. If you have any problems though, please note it in a comment, or post a defect. Remember, you can't edit a comment once it's posted, so apply any formatting before hitting submit!

What kind of feedback?

It's easy to give feedback, and we welcome all kinds of comment, but if you need some guidance on how to give a review, here are a few suggestions for how you can give us feedback.

Recommend a Page

Tell us which pages we should have by leaving a link and a note in the Requested Items section of the Technical Communications Work in Progress page.