×
Namespaces

Variants
Actions
Revision as of 02:20, 9 November 2012 by hamishwillee (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Help:Wiki Article Review Checklist

From Nokia Developer Wiki
Jump to: navigation, search
Help.png
This Help topic provides a checklist of review criteria to consider when you're reading an article.

Ideally you'll fix these yourself and then update the reviewer information in the ArticleMetaData template timestamp and reviewer fields. If an article can't be fixed then and there, add a polite comment for the author (and other users) explaining what improvements might be made. Also add the ArticleNeedsUpdate template so that the article is highlighted as needing attention. Checklist topics are shown below.

Contents

Check article title is descriptive and unambiguous

Article names should:

  • be concise, descriptive and unambiguous
  • use correct spelling.

Consider whether a user seeing the topic in a list will understand broadly whether it is relevant to their needs - include the development framework, platform, and/or platform version, where the article is specific to that platform.

Some examples of good titles:

  • Learning to program Symbian C++ is appropriate for an article on Symbian C++ only. Learning to program would be a high level topic covering programming on all frameworks and platforms
  • Location Services on Symbian would covers the location services on Symbian for all development frameworks (ie Java, C++, Python etc), while Location Services using Symbian C++ would cover location services in that programming language.
  • Getting the Location in S60 1st Edition devices is an article that covers just a particular platform and version. Usually we would include this information as a section in a document covering all versions - however it can be useful to have a topic like this prior to archiving old content.

There is more information in the manual of style.

Check the categories

Check that helpful categories have been applied:

  • Usually includes a development framework (e.g. Qt) and a technology area (e.g. Connectivity).
  • Add categories for all relevant platforms - ie cross-platform Qt articles would have both MeeGo and Symbian.
  • Where possible you should use the most specific categories available - e.g. for a topic related to a Bluetooth game using Qt Quick for the UI you would have categories Qt Quick, Bluetooth and Games (there is no need for Qt and Connectivity as well).

For further guidance see Help:Categories

Does it belong on the wiki?

With the correct category, the wiki can host almost any article. The general rule is that if an article is useful or of interest to Nokia platform developers it is acceptable.

If an article is of no use to developers (e.g. too badly written or has no technical content) it should be considered for deletion (Apply Template:DeleteMe).

Is it complete?

Does the article cover the topics an author would reasonably expect from its title and Abstract? If not, then it may be necessary to add ArticleNeedsUpdate or Stub templates explaining what is missing. Minimally add a comment with bullet points explaining what you think is needed.

Is this a duplicate of another document?

Where possible there should only be one document on a particular topic. Similar topics should be merged if at all possible.

Is the content technically accurate and up to date

  1. Does the content refer to the lastest tools? For example, a Qt article that suggests you use Carbide.c++ should perhaps be updated to suggest Qt Creator. Similarly, Aptana is deprecated in favour of Nokia Web tools
  2. Does it use recommended APIs
  3. Is there a better way of achieving the technical goal

Does the article use the recommended templates?

We recommend that two templates are applied to the top of every article:

  • ArticleMetaData contains information about the article including the SDKs and devices it was tested against, the platforms and devices it is compatible with, any associated source code examples or test downloads, whether it needs to be signed, and when it was created, reviewed and last changed, and by whom. All information that is relevant to the article should be filled in.
  • Abstract is applied before the first heading (or sometimes just after it) to describe what the article is about. This may be used to describe the article in external lists.

Is the article readable?

Is the article clear and easy to read? Does it have any obvious spelling mistakes or structural issues. Does it need a subedit?

Has it got a downloadable code example?

Articles that supply code snippets are useful, but articles that have complete code examples (e.g. in a zip) are even more useful. If an article has code snippets propose the addition of a buildable project and a downloadable installation file to allow users to try it out.

If the article does have a downloadable code example, does it run on current devices.

Ideally code samples should be hosted on the wiki itself (over time external links may break)

Would the article benefit for more images or other bling?

Articles with too many images can be distracting. However adding a screenshot to illustrate something cool you have done or a particular issue with your design can make the article more useful. Usually these are better at the top of the article below the abstract.

Does the article have useful references?

Articles should cross link to the developer library where there is useful official content - for example API reference.

Do the article's links all work?

Test key external links to verify they work.

Does the article use consistent and appropriate style markup

Style markup like bold, italic, monotype can make it easier to identify "types" of information while reading (e.g. code object names, filenames, tool names) and to highlight content that is particularly "important". Do not to overuse styles or to use them inconsistently: this makes it impossible for readers to work out what is important.

We recommend the following markup rules

  • Bold for marking up filenames (e.g. myfile.xml) and buttons that must be pressed (e.g. press the OK button.)
  • Link to API reference for first mention of a new class, method or namespace "inline" in text
  • Monotype for marking up subsequent code objects "inline" in the text - using {{Icode|ClassOrFunction}}. For example: "Use foo() to start the operation"
  • Italic for tool names.

These styles can also be used for highlighting other important sections of text, but use sparingly!

 
×