Rosetta Code:Add a Task
Prerequisites
Draft vs non-draft
Not all tasks are immediately ready to be thrown at the casual Rosetta Code participant. Some need a review or draft phase before they're in good shape.
- For a non-draft task, one would use Template:Task by putting {{task}} at the top of the page.
- To note that a task is a draft, use Template:draft task, by putting {{draft task}} at the top, rather than {{{task}}}.
It's up to you to decide which you start with, but another community member may choose to change your created task to a draft. If there is some question on the general suitability of the task then create a draft task and discuss the reason for it being a draft in the talk page. This will warn potential contributors that there may be substantial changes in the task description whilst still in draft status.
Reasons for draft status
Reasons for draft status might include, but not be limited to:
- A task that is too large.
- A task that is too general and so hard to compare implementations.
- A task that may be too specific and so only implementable by a single language.
Task focus inclusion
Generally speaking, the goal is to address a problem a programmer may face or want to think about. These include (but aren't strictly limited to):
- Practical problems
- Problems which demonstrate concepts
- Simple entertainment.
As for discouraged areas, remember that Rosetta Code is a tool of education, not a code repository. "Code golf", or the finding of the absolute most succinct expression of a solution as its own goal, is rarely idiomatic or practical use of the languages in question, and so is also difficult to justify in a demonstrative context.
The common theme across all tasks must be increasing competence and understanding of the tools in question, by example or by annotated counterexample if necessary.
Task focus exclusion
A task should not be so specific as to invoke a particular language as being the only one allowed to solve a task. Tasks which specify a particular language will not tend to achieve many useful comparisons or solutions, as languages are the richest resource on Rosetta Code.
A task should also not be so specific with its other requirements that there is only one language capable of solving it. Specifically requiring language features et al such that it is unlikely that there would be multiple nominally-distinct languages that can satisfy the task requirements is equivalent to invoking a specific language, and so leads to the same problems.
A caveat, however, is that best-effort solutions ("this isn't exactly possible in Ayrch, but something practical solving the language's idiomatic analog would be") are often fine, so a task writer may find that styles "use technique X to solve problem" and "solve problem using technique X" may need to be interchanged to make a useful number of solutions possible.
Basic information
A task needs a few basic components. It neeeds a simple description of the problem. Having a solution to the task allows you to tune the task description such that the run times and/or size of outputs are reasonable.
Inline references to specifically-related information are important. While offsite links are often necessary (if only for appropriate citation), enough cited, excerpted information should be included such that the task may still be solved.
Where relevant, sample input should be included; it gives task solvers something to work with.
Example code
It is usually a good idea to have at least one example implementation completed, tested, and working before you start writing the description of the task, as well as a sample of correct output. It is usually a good idea if this first example shows its output; even if it isn't strictly necessary for the completion of the task, it helps other implementers understand the task and what they need to do.
Additional information
Semantic annotations
If your task invokes particular concepts (and it should; that's part of what a task is supposed to do), these should be marked with semantic notation. This will help better organize your task on Rosetta Code. To take an example, excerpted and modified from Delegates:
A delegate is a helper object used by another object. The delegator may send the delegate certain messages, and provide a default implementation when there is no delegate or the delegate does not respond to a message.
This could be annotated like this:
A delegate is a [[task concept::helper object]] used by another object. The delegator may send the delegate certain [[task concept::message|messages]], and provide a default implementation when there is no delegate or the delegate does not respond to a message.
This links the task with a property named "task concept" using "helper object" and "message" as the relation.
Lurk!
Read existing task descriptions, and model yours after ones you like. If you follow the Recent Changes feed, you can watch the creation of one, live. Alternately, you might take a look at the edit history of existing tasks (and their talk pages), to get a feel of the process and the (unwritten) "house style."
Hang around, answer and solicit questions in your task's talk pages, especially in its early days. (It may help to Watch the task's talk page, if you're so inclined) This will ensure that people have enough information to implement the task in other languages, allow you (and them) to fine tune the task description as needed, and ultimately end up with something many can implement without ambiguity.
Jargon
It helps to explain jargon, as about the only common jargon that's likely be understood would be in the fields of programming or computer science&emdash;and even that's not guaranteed (this is an educational site, after all). Be especially aware of unexplained maths jargon, and watch the talk page and other implementations for signs that the task description may not be sufficiently clear.
Extreme Language
Some schools, libraries and parental filters filter pages whose URLs match wordlists. This even occasionally impacts Rosetta Code's reCAPTCHA API key. We try to include this audience, so please self-sensor such content. (For an example, see the discussion page for language Category talk:Brainf***).