1
\$\begingroup\$

So, I'm working on an environment for an upcoming challenge, and I've written a fairly extensive API document for entries to interact with the game.

I'm thinking at this stage that the API doc itself is longer than most posts, and it might make the challenge more approachable to describe the challenge, game rules, how to enter etc. in the question and then link to the API doc.

I'm also considering linking to an existing wiki page for the rules of the game.

For context, the challenge involves my JS code as a controller for the game, so people will have to use either the Github Pages environment or (probably more likely) a clone of the git repository to develop their entry.

So, the generic question is this: Is it acceptable to shorten challenges by linking to external resources in order to shorten code challenge pages?

Here's my current thought process on the matter.

Disadvantages:

  • More links means more pages to keep track of.
  • If a linked page is not in my control, it could be changed/vandalised during the challenge.
  • It could prevent access for some users (e.g. if their country blocks a site).

Advantages:

  • The challenge question itself becomes clearer and more manageable.
  • Someone else may have already described something better than I can.
  • Users can focus on one aspect of the challenge at a time (e.g. learning the game, writing their entry, deploying their entry)
  • If it's in the git repository, I could deploy code changes and doc changes at the same time, ensuring the docs don't fall out of date.
  • If issues come up during the challenge, I could add a FAQ page for users who experience the same issues.
  • Two sides of an asymmetrical challenge could link to the same resource, keeping the two in sync.

Possible resources to refer to (I'm not thinking of making all of these separate, most of these are for discussion):

  • Interface documents
  • Background information
  • Required code (if cloning a repo would be useful)
  • Live environment for code
  • Troubleshooting information/FAQ page
  • Example entries (as starting points)
  • Guide to entering

Note: For this particular challenge, it will be possible to write, test and post an entry with the GH Pages environment. So it will be possible to play the game without a github account.

\$\endgroup\$
2
\$\begingroup\$

This would be perfectly fine

Just make sure you include the list of available functions in the question.

A controller is the component which will make requests of the board to allow a player (human or computer) to interact with the game. It will implement the contract below:

constructor(board, side)
Board state:
turn() - Current turn of the game
scores() - The current score
spaces() - Every space, and what's in it
space_info(x, y) - Detailed information on any space on the board.
dwarves() - The location of every dwarf
trolls() - The location of every troll
indexed_dwarves() - The location of every dwarf with a fixed index
indexed_trolls() - The location of every troll with a fixed index
previous_move() - What got moved to where last turn
For turns:
check_space(x, y)- Find out what moves are available from a given space
select_space(x, y) - The player decides to move a piece at space.
check_move(x, y) - Find out what will happen if you move to a place
move(x, y) - The player moves the current piece to the selected space.
Utility:
current_space - Currently selected space (not a function)
clear_space() - Empties currently selected space
declare(game_over) - Say whether or not your player thinks no more progress can be made on the game.
opponent_declared() - Has the opponent declared the game over?
Every game will have two controllers, dwarf and troll, belonging to two players, dwarf and troll.

Other than that, detailed information is perfectly fine to host externally.

\$\endgroup\$

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .