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.
- 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).
- 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.